{"owner":"icebear0828","repo":"codex-proxy","hasSkills":true,"totalSkillsCount":26,"totalTokensCount":18823,"categories":["anthropic-skill","root-instruction","plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/issue-create/SKILL.md",".agents/skills/issue-create/assets/bug-report.md",".agents/skills/issue-create/assets/feature-request.md",".agents/skills/issue-create/assets/perf-report.md",".agents/skills/issue-create/assets/question.md",".agents/skills/issue-create/references/issue-types.md",".agents/skills/issue-create/references/labels.md",".agents/skills/pr-push/SKILL.md",".agents/skills/pr-push/assets/pr-body-template.md",".agents/skills/pr-push/references/changelog-format.md",".agents/skills/pr-push/references/commit-conventions.md",".agents/skills/pr-push/references/pr-checklist.md",".claude/skills/issue-create/SKILL.md",".claude/skills/issue-create/assets/bug-report.md",".claude/skills/issue-create/assets/feature-request.md",".claude/skills/issue-create/assets/perf-report.md",".claude/skills/issue-create/assets/question.md",".claude/skills/issue-create/references/issue-types.md",".claude/skills/issue-create/references/labels.md",".claude/skills/pr-push/SKILL.md",".claude/skills/pr-push/assets/pr-body-template.md",".claude/skills/pr-push/references/changelog-format.md",".claude/skills/pr-push/references/commit-conventions.md",".claude/skills/pr-push/references/pr-checklist.md","AGENTS.md","packages/npm/README.md"],"skills":{".agents/skills/issue-create/SKILL.md":"---\nname: issue-create\ndescription: >-\n  Interview the user to gather all required context, then open a high-quality GitHub issue (`gh issue create`) on the codex-proxy repo with the right template, labels, and structured body.\n  TRIGGER when: user says \"open an issue\", \"file an issue\", \"create issue\", \"report a bug\", \"feature request\", \"提个 issue\", \"报 bug\", \"提需求\".\n  DO NOT TRIGGER when: user wants to view, search, comment on, or close existing issues (use `gh issue list/view/comment/close` directly); user is writing a PR description (use `pr-push`).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Write\"\n---\n\n# Issue Create\n\nGather complete context through a structured interview, then file a well-formed issue. The interview is a hard gate — vague issues waste maintainer time.\n\n## Overview\n\nMost \"I have a bug\" or \"I want a feature\" reports are missing the information a maintainer needs to act. This skill runs a four-phase interview, fills the appropriate template, applies the right labels, and only then calls `gh issue create`. The user sees and approves the rendered body before submission.\n\n## When to Use\n\n- A user wants to file a new issue on the codex-proxy repository.\n- A user describes a bug or feature in conversation and asks \"should we file an issue?\"\n\n## Important Rules\n\n1. **The interview is not optional.** Do NOT call `gh issue create` until all required fields for the chosen type are collected and the user has explicitly approved the rendered body.\n2. **Never invent reproduction steps, version numbers, log output, or behavior.** If the user did not provide it, ask. If they cannot provide it, write \"not provided\" in the field, do not fabricate.\n3. **Show the full body before submitting.** The user must explicitly say \"submit\" / \"looks good\" / equivalent. \"Yes\" without seeing the body is not enough — show it first.\n4. **Apply only labels from the project's existing label set.** Read `references/labels.md` for the catalog. Do not invent new labels.\n5. **Strip secrets.** If the user pastes logs, headers, or config that contain tokens, cookies, OAuth state, API keys, or account IDs, redact them before they enter the issue body. Replace with `<redacted>`.\n6. **One issue per scope.** If the user describes two unrelated problems, file two issues. Ask before splitting.\n\n## Key Workflows\n\n### Phase 1: Type classification\n\n**Goal:** Pick the right template and label.\n\nAsk the user (one consolidated question):\n\n> What type of issue is this?\n>   1. **Bug** — something is broken or behaves incorrectly\n>   2. **Feature request** — propose new functionality\n>   3. **Question** — usage / configuration / \"is this expected?\"\n>   4. **Performance** — measurable regression or slowness\n>   5. **Documentation** — docs are wrong, missing, or unclear\n\nRead the type spec:\n```\nRead: .Codex/skills/issue-create/references/issue-types.md\n```\n\nMap answer to template path:\n\n| Type | Template asset | Default label |\n|---|---|---|\n| Bug | `assets/bug-report.md` | `bug` |\n| Feature request | `assets/feature-request.md` | `enhancement` |\n| Question | `assets/question.md` | `question` |\n| Performance | `assets/perf-report.md` | `bug` |\n| Documentation | `assets/feature-request.md` (with docs framing) | `documentation` |\n\nDo **NOT** proceed to Phase 2 until the type is confirmed.\n\n### Phase 2: Required-field interview\n\n**Goal:** Collect every field the chosen template requires.\n\nRead `references/issue-types.md` to see the required-field table for the chosen type. Ask for missing fields in **one consolidated message**, not one at a time. Group related fields together.\n\n**For bugs**, the required fields are:\n- One-line summary\n- Expected behavior\n- Actual behavior\n- Reproduction steps (numbered)\n- Codex-proxy version (`npm pkg get version` or app About dialog)\n- Deployment mode (Electron app / Docker / `npm start` / dev)\n- Relevant log lines (redact secrets)\n- Frequency (always / intermittent / once)\n\n**For feature requests**, the required fields are:\n- Problem the feature solves (user-facing motivation, not the proposed solution)\n- Proposed solution (high level)\n- Alternatives considered\n- Who benefits (single user / all users / specific deployment mode)\n\n**For questions**:\n- What you tried\n- What you expected\n- What happened\n- Relevant config (redact secrets)\n\n**For performance**:\n- All bug fields, plus:\n- Measured baseline vs current (timings, memory, request count — be specific)\n- Reproduction harness (script, steps, or `tests/bench/`)\n\n**For documentation**:\n- Which doc page / file\n- What is wrong or missing\n- Suggested fix (if any)\n\nIf a field cannot be answered, the user must explicitly say \"not applicable\" or \"unknown\" — record that verbatim. Do not silently skip.\n\nDo **NOT** proceed to Phase 3 until every required field has either an answer or an explicit \"not applicable\".\n\n### Phase 3: Code & related-context grounding\n\n**Goal:** Help maintainers find the relevant code fast.\n\nAsk the user for:\n- File paths or `file:line` references they suspect are involved (optional but encouraged).\n- Related issues / PRs to link (`Refs #N`, `Related to #N`).\n- Whether they tried searching existing issues (`gh issue list --search \"<keywords>\"`). If they have not and the report sounds like something that might exist, run the search and show top 3 matches before continuing.\n\nIf the user provides no code locations and the bug is concrete, optionally offer:\n> \"Want me to grep for the relevant code so we can include file:line in the issue?\"\n\nDo not grep silently — ask first, and only do it once.\n\n### Phase 4: Render, confirm, submit\n\n**Goal:** Show the final body, get explicit approval, file the issue.\n\n1. Read the chosen template:\n   ```\n   Read: .Codex/skills/issue-create/assets/<template>.md\n   ```\n2. Read the labels catalog:\n   ```\n   Read: .Codex/skills/issue-create/references/labels.md\n   ```\n3. Fill the template with the collected fields. Strip secrets per Important Rule #5.\n4. Pick labels:\n   - Always include the type label (Phase 1 mapping).\n   - Add `good first issue` only if the user explicitly says it qualifies (small scope, low context required).\n   - Add `help wanted` if the user has no plan to fix it themselves.\n   - Add `documentation` in addition to the type label if docs need updating.\n5. Show the user the complete rendered output:\n   ```\n   Title: <title>\n   Labels: <label1>, <label2>\n   Body:\n   <full body>\n   ```\n6. Ask: \"Ready to submit, or want to adjust anything?\"\n7. Wait for an explicit affirmative. \"Yes\", \"submit\", \"go\", \"looks good\", \"提交\" all qualify. Silence or hedging does not.\n8. Submit:\n   ```bash\n   gh issue create \\\n     --title \"<title>\" \\\n     --label \"<label1>,<label2>\" \\\n     --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n9. Print the issue URL.\n10. **STOP.** Do not assign, do not comment, do not link to projects unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not call `gh issue create` before showing the body for approval.\n- Do not invent reproduction steps when the user gave a vague report — ask.\n- Do not paste raw logs that contain tokens / cookies / OAuth state / account IDs.\n- Do not apply labels outside the existing catalog.\n- Do not file two issues from one report without confirming the split with the user.\n- Do not grep / search the codebase silently to \"fill in\" missing fields — ask first.\n",".agents/skills/issue-create/assets/bug-report.md":"<!--\nBug report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nMatch the language of the repo's existing issues (currently a mix of zh-CN and en).\n-->\n\n## Summary\n\n{{One sentence describing the bug.}}\n\n## Expected behavior\n\n{{What the user thought would happen.}}\n\n## Actual behavior\n\n{{What actually happened.}}\n\n## Reproduction steps\n\n1. {{step 1}}\n2. {{step 2}}\n3. {{step 3 — describe the failure}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| Frequency | {{always / intermittent / once}} |\n| First broken version (if known) | {{version or \"unknown\"}} |\n| Workaround (if any) | {{description or \"none\"}} |\n\n## Logs / output\n\n```\n{{Paste relevant log lines. SECRETS REDACTED — no tokens, cookies,\noauth_state, API keys, account IDs.}}\n```\n\n## Additional context\n\n{{Anything else the maintainer should know. Remove this section if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n",".agents/skills/issue-create/assets/feature-request.md":"<!--\nFeature request template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\n-->\n\n## Summary\n\n{{One sentence describing the feature.}}\n\n## Problem\n\n{{The user-facing motivation. What can the user not do today, or what is\npainful about how they have to do it? DO NOT describe the proposed\nsolution here — only the problem.}}\n\n## Proposed solution\n\n{{High-level description of how the feature would work. Implementation\ndetail is welcome but not required. If you have a UI in mind, sketch\nor screenshot helps.}}\n\n## Alternatives considered\n\n{{Other approaches the user thought about and why they don't fit.\nEven \"I considered X but it doesn't work because Y\" is useful — it\nsaves the maintainer from re-deriving the same conclusion.}}\n\n## Who benefits\n\n{{single user / all users / a specific deployment mode (Electron / Docker / dev) /\na specific upstream provider / a specific account state}}\n\n## Impact if not done\n\n{{Does the user have a workaround? Is this blocking? Nice-to-have?\nRemove this section if \"no impact, just nice\".}}\n\n## Additional context\n\n{{Mockups, links, related discussions. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n",".agents/skills/issue-create/assets/perf-report.md":"<!--\nPerformance report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nA perf report without numbers is just a bug — switch to bug-report.md if\nno measurements are available.\n-->\n\n## Summary\n\n{{One sentence describing the regression or slowness.}}\n\n## Expected behavior\n\n{{What performance was expected, and where that expectation comes from\n(prior version, docs, comparable system).}}\n\n## Actual behavior\n\n{{What is observed instead.}}\n\n## Measurements\n\n| Metric | Baseline | Current | Delta |\n|---|---|---|---|\n| {{e.g. p95 latency}} | {{200ms}} | {{1.4s}} | {{+600%}} |\n| {{e.g. memory RSS}} | {{180MB}} | {{420MB}} | {{+133%}} |\n\n**Methodology:** {{How the numbers were taken — script, manual stopwatch,\nprofiler, load test. Be specific enough that a maintainer can reproduce.}}\n\n## Reproduction harness\n\n```\n{{Script, `tests/bench/...` reference, or numbered steps. Must be\ndeterministic enough to re-measure.}}\n```\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| First slow version (if known) | {{version or \"unknown\"}} |\n| Resource constraint hit | {{CPU / memory / network / FDs / \"none\"}} |\n\n## Logs / output\n\n```\n{{Relevant log lines or profiler output. SECRETS REDACTED.}}\n```\n\n## Additional context\n\n{{Anything else. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n",".agents/skills/issue-create/assets/question.md":"<!--\nQuestion template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nNote: if it turns out to be a bug, switch to the bug-report template.\n-->\n\n## What I'm trying to accomplish\n\n{{The end goal, not the immediate confusion. e.g. \"I want to route\ngpt-5.5 traffic only to my work account\" — not \"what does\nplan_mapping do?\"}}\n\n## What I tried\n\n{{Commands, config snippets, docs read, search terms used. Be specific.}}\n\n```yaml\n# Relevant config — SECRETS REDACTED\n{{config snippet or \"none\"}}\n```\n\n## What I expected\n\n{{What outcome did you anticipate?}}\n\n## What happened\n\n{{What did you actually observe?}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n\n## Additional context\n\n{{Logs, screenshots, anything else. Remove if empty.}}\n",".agents/skills/issue-create/references/issue-types.md":"# Issue Type Specs\n\nRequired and optional fields per issue type. The skill enforces \"required\" — every required field must have either an answer or an explicit \"not applicable\" / \"unknown\" before the issue can be filed.\n\n## Bug\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Becomes part of the title; ≤72 chars |\n| Expected behavior | yes | What the user thought would happen |\n| Actual behavior | yes | What actually happened |\n| Reproduction steps | yes | Numbered list, deterministic |\n| Codex-proxy version | yes | `npm pkg get version` or About dialog |\n| Deployment mode | yes | Electron / Docker / `npm start` / dev / source |\n| OS + arch | yes | e.g. macOS 14.5 arm64, Windows 11 x64, Ubuntu 22.04 x64 |\n| Relevant logs | yes | Redact secrets; \"none\" is acceptable |\n| Frequency | yes | always / intermittent / once |\n| Workaround | no | If the user found one |\n| First broken version | no | If known (helps bisect) |\n| Related issues | no | `Refs #N` |\n\n## Feature Request\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Title material |\n| Problem statement | yes | The user-facing motivation. NOT the proposed solution. |\n| Proposed solution | yes | High level; implementation detail is welcome but optional |\n| Alternatives considered | yes | Even \"I considered X but it doesn't fit because Y\" |\n| Who benefits | yes | single user / all users / specific deployment mode / specific upstream |\n| Impact if NOT done | no | Does the user have a workaround? Is this blocking? |\n| Related issues / PRs | no | `Refs #N` |\n| Mockups / sketches | no | For UI features |\n\n## Question\n\n| Field | Required | Notes |\n|---|---|---|\n| What you're trying to accomplish | yes | The end goal, not the immediate confusion |\n| What you tried | yes | Commands, config, links to docs read |\n| What you expected | yes | |\n| What happened | yes | |\n| Relevant config | yes | Redact secrets; \"none\" if no config involved |\n| Codex-proxy version | yes | |\n| Deployment mode | yes | |\n\nIf a \"question\" turns out to be a bug during the interview, switch to the Bug template — do not file under `question`.\n\n## Performance\n\nAll Bug fields, plus:\n\n| Field | Required | Notes |\n|---|---|---|\n| Baseline measurement | yes | Numbers from a known-good version or expected baseline |\n| Current measurement | yes | Same metric, current version |\n| Measurement methodology | yes | How the numbers were taken — script, manual stopwatch, profiler |\n| Reproduction harness | yes | Script, `tests/bench/...` reference, or steps |\n| Resource constraint hit | no | CPU, memory, network, file descriptors, etc. |\n\nA perf report without numbers is a bug report — switch templates.\n\n## Documentation\n\n| Field | Required | Notes |\n|---|---|---|\n| Doc location | yes | File path (`README.md`, `CLAUDE.md`, `docs/...`) or URL |\n| What is wrong / missing | yes | Specific quote of the offending text, or \"this section is missing\" |\n| Suggested fix | no | Welcome but not required |\n| Audience affected | no | New users / operators / contributors / API consumers |\n",".agents/skills/issue-create/references/labels.md":"# Issue Labels (codex-proxy)\n\nThe complete catalog of labels currently defined on the repo. Apply only labels from this list — do not invent new ones. To propose a new label, file a `chore:` issue separately.\n\n| Label | Color | Use for |\n|---|---|---|\n| `bug` | #d73a4a | Something isn't working as documented or intended |\n| `enhancement` | #a2eeef | New feature or extension of an existing feature |\n| `documentation` | #0075ca | Improvements or additions to documentation |\n| `question` | #d876e3 | Further information is requested; not yet known to be a bug |\n| `help wanted` | #008672 | Maintainers welcome contributors to take this on |\n| `good first issue` | #7057ff | Small scope, low context required, friendly to newcomers |\n| `duplicate` | #cfd3d7 | Already filed elsewhere — set after triage, not on creation |\n| `invalid` | #e4e669 | Not actionable or out of scope — set after triage |\n| `wontfix` | #ffffff | Acknowledged but will not be addressed — set after triage |\n| `sync-conflict` | #d73a4a | `main → electron` auto-sync merge conflict — used by automation, not for human-filed issues |\n\n## Application rules for the skill\n\n1. **One type label minimum**: bug / enhancement / documentation / question (pick exactly one based on the issue type).\n2. **`good first issue`**: only when the user explicitly confirms the scope is small AND the fix is local (single file or single module).\n3. **`help wanted`**: when the reporter has no plan to send a PR themselves.\n4. **`documentation`** can be combined with `bug` or `enhancement` if the change requires both code and doc updates.\n5. **Never apply on creation**: `duplicate`, `invalid`, `wontfix`, `sync-conflict`. These are triage / automation labels.\n\n## CLI form\n\n```bash\ngh issue create --label \"bug,help wanted\" ...\n```\n\nMultiple labels are comma-separated (no space after the comma).\n",".agents/skills/pr-push/SKILL.md":"---\nname: pr-push\ndescription: >-\n  Package the current working changes into a standards-compliant codex-proxy pull request:\n  branch hygiene, commit message linting, CHANGELOG prompt, conventional commit, push, and `gh pr create` against the `dev` branch.\n  TRIGGER when: user asks to \"push a PR\", \"open a PR\", \"create PR\", \"ship this\", \"推 PR\", \"开 PR\", \"提交 PR\".\n  DO NOT TRIGGER when: user only wants to commit without pushing; user explicitly wants to push directly to main; user wants to merge, rebase, or close an existing PR (use `gh pr merge` / `gh pr close` directly).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Edit\"\n  - \"Write\"\n  - \"Grep\"\n---\n\n# PR Push\n\nTurn the current working tree into a clean PR targeting `dev`. This skill enforces codex-proxy's contribution rules so community maintainers do not have to memorize them.\n\n## Overview\n\nCodex-proxy uses a `dev` → `main` promotion flow with strict commit conventions, CHANGELOG discipline, and a pre-push validation hook. This skill walks the maintainer through an interview, makes the commit, runs the push (letting the hook gate quality), and opens the PR. It explicitly stops before merge — review and merge are separate human decisions.\n\n## When to Use\n\n- A maintainer has finished a unit of work in their working tree and wants it on `dev`.\n- A maintainer asks to \"open a PR\" or equivalent and the working tree has changes (staged, unstaged, or untracked).\n\n## Important Rules\n\n1. **Target branch is always `dev`.** Never open a PR against `main` unless the user explicitly states \"target main\" with a written reason. The `main` branch is fast-forwarded by the `promote-dev-to-main.yml` workflow — manual PRs to `main` break that contract.\n2. **Never commit on `dev` or `main` directly.** If `git branch --show-current` is one of these, stop and ask the user to name a feature branch (`git switch -c <name>`).\n3. **Never use `git add -A`, `git add .`, or `git add -f`.** Stage files by explicit path. `-f` overrides `.gitignore` and has been the cause of secret leaks elsewhere.\n4. **Never pass `--no-verify` to `git commit` or `git push`.** The hook is the gate. If it fails, fix the underlying issue, do not bypass.\n5. **Stop after `gh pr create`.** Do not merge, do not approve, do not enable auto-merge. Pushing a PR and merging a PR are two human decisions.\n6. **CHANGELOG gate.** If any file under `src/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` changed, `CHANGELOG.md`'s `[Unreleased]` section MUST have a new entry covering the change before the commit is created.\n7. **Commit message format is fixed:** `<type>(<optional-scope>): <imperative summary>`. The type set is enumerated in `references/commit-conventions.md`.\n\n## Key Workflows\n\n### Phase 1: Discovery (interview, do not touch the repo yet)\n\n**Goal:** Understand what is being shipped before any git operation.\n\nRun these read-only commands in parallel and summarize results back to the user:\n\n```\ngit branch --show-current\ngit status --short\ngit diff --stat\ngit log --oneline -10\n```\n\nThen read the conventions:\n```\nRead: .Codex/skills/pr-push/references/commit-conventions.md\nRead: .Codex/skills/pr-push/references/changelog-format.md\nRead: .Codex/skills/pr-push/references/pr-checklist.md\n```\n\nAsk the user (in one consolidated message) for any field that cannot be inferred:\n\n- **Commit type** (feat / fix / refactor / docs / test / chore / perf / ci) — propose one based on the diff, ask for confirmation.\n- **One-line summary** (imperative, lowercase, no trailing period) — propose one based on the diff.\n- **PR target** — default `dev`. Confirm only if the user previously asked to deviate.\n- **CHANGELOG entry** — if the gate in Important Rules #6 applies and `CHANGELOG.md` `[Unreleased]` has no matching entry, ask the user to dictate one (or offer to draft one for review). Do not invent silently.\n- **Memory / docs touch** — if the change touches public protocol, request flow, auth lifecycle, or release infra, ask whether `AGENTS.md` needs updating in the same PR.\n\nDo **NOT** proceed to Phase 2 until the user has explicitly confirmed (a) commit type, (b) summary, (c) CHANGELOG status, (d) target = `dev`.\n\n### Phase 2: Branch hygiene\n\n**Goal:** Make sure the commit lands on a feature branch, not on `dev`/`main`.\n\n1. Check `git branch --show-current`.\n2. If the current branch is `dev` or `main`:\n   - Stop. Ask the user to provide a feature branch name (suggest one derived from the commit summary, kebab-case, ≤40 chars).\n   - Run `git switch -c <name>`. Do not auto-pick a name without confirmation.\n3. If the current branch is a feature branch but is not based on up-to-date `origin/dev`:\n   - Run `git fetch origin dev`.\n   - If `git merge-base --is-ancestor origin/dev HEAD` is false (branch is behind), warn the user and ask whether to `git rebase origin/dev` before continuing. Do not rebase silently.\n\n### Phase 3: Stage + commit\n\n**Goal:** Produce one well-formed commit.\n\n1. List the files the user wants in this commit. If they didn't say, propose the list from `git status --short` and confirm.\n2. Run `git add <file1> <file2> ...` with explicit paths. Never `-A`, `.`, or `-f`.\n3. If CHANGELOG was updated as part of Phase 1, include `CHANGELOG.md` in the staged set.\n4. Build the commit message:\n   - First line: `<type>(<scope>): <summary>` — scope is optional, omit parentheses if no scope.\n   - Body (optional): wrap at ~72 cols, explain *why*, reference issues with `Closes #N` / `Refs #N` if applicable.\n5. Commit with a HEREDOC (preserves formatting):\n   ```bash\n   git commit -m \"$(cat <<'EOF'\n   <type>(<scope>): <summary>\n\n   <optional body>\n   EOF\n   )\"\n   ```\n6. If the commit fails because of a pre-commit hook, fix the reported issue and create a NEW commit (do not `--amend`). Re-run the same command after fixes.\n\n### Phase 4: Push\n\n**Goal:** Get the branch to `origin` so a PR can be opened.\n\n1. Confirm the user wants to push (a single short \"ready to push?\" — they may have wanted to inspect the commit first).\n2. **Hook presence check.** The repo's pre-push gate lives at `.Codex/hooks/pre-push-validate.sh`, which is gitignored — fresh clones do **not** have it. Run `test -x .Codex/hooks/pre-push-validate.sh`:\n   - **Hook present** → push normally; the hook will run.\n   - **Hook missing** → warn the user that no pre-push gate is installed, then run the equivalent checks inline based on what the diff touched, before pushing:\n     | Diff touches | Run |\n     |---|---|\n     | `src/**` or `tests/**` | `npm test` and `npx tsc --noEmit` |\n     | `web/**` | `npm run build` |\n     | `Dockerfile`, `docker-compose*` | `docker build .` (or note user must verify) |\n     | `packages/electron/**`, `electron-builder.yml` | `npm run -w packages/electron build` |\n     | `native/**` | `npm run -w native build` |\n     Any failure aborts the push — fix and re-run.\n3. Run `git push -u origin HEAD`.\n4. If the push is blocked by the hook:\n   - Read the hook output verbatim back to the user.\n   - The hook validates the build targets affected by the diff (test, tsc, web build, Dockerfile lint, Electron config, native addon). Identify which target failed and propose a fix.\n   - **Never retry with `--no-verify`.** Re-run the offending check locally, fix the root cause, amend the commit only if the user authorizes it, otherwise add a fix-up commit.\n\n### Phase 5: Open the PR\n\n**Goal:** Create a PR against `dev` with a body that future reviewers can read cold.\n\n1. Read the PR body template:\n   ```\n   Read: .Codex/skills/pr-push/assets/pr-body-template.md\n   ```\n2. Determine PR title:\n   - If the branch has a single commit, reuse the commit subject.\n   - If multiple commits, propose a title that summarizes the branch's intent and confirm with user.\n   - Title MUST start with a conventional type, MUST be ≤72 chars.\n3. Fill the body sections (Summary / Test Plan / Notes). Source content from:\n   - `git log <base>..HEAD` for the change list.\n   - The CHANGELOG entry the user wrote.\n   - Test commands actually run locally (do not invent test results).\n4. Show the rendered title + body to the user. **Wait for explicit \"looks good\" before invoking `gh`.**\n5. Create the PR:\n   ```bash\n   gh pr create --base dev --title \"<title>\" --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n6. Print the PR URL.\n7. **STOP.** Do not run `gh pr merge`, `gh pr review --approve`, `gh pr edit --add-label`, or `--auto-merge` unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not assume the user wants every modified file in the PR — ask.\n- Do not auto-write the CHANGELOG entry without showing it for approval first.\n- Do not retry a failing pre-push hook with `--no-verify`.\n- Do not open the PR against `main` even if the user is on a branch named `main-fix-X` — branch name does not imply target.\n- Do not silently rebase. If the branch needs rebase against `origin/dev`, ask first.\n- Do not chain `gh pr create` with `gh pr merge`. Two separate decisions.\n",".agents/skills/pr-push/assets/pr-body-template.md":"<!--\nPR body template for codex-proxy. The skill fills in the {{placeholders}}\nand removes optional sections that don't apply. Default language follows\nthe repo's dominant language (currently zh-CN for CHANGELOG entries,\nen for code/commits). Pick one and stay consistent within a single PR.\n-->\n\n## Summary\n\n{{One paragraph: WHAT changed and WHY. Reference the user-visible impact.\nIf multiple commits, summarize the branch's intent, not each commit.}}\n\n## Changes\n\n{{Bulleted list mirroring the CHANGELOG entry. Group by area when the PR\ntouches multiple modules. Reference file paths so reviewers can navigate.}}\n\n- {{change 1 — files}}\n- {{change 2 — files}}\n\n## Test Plan\n\n{{List the commands actually run locally. Do not invent results.\nMark checked items with [x], unchecked with [ ].}}\n\n- [ ] `npm test`\n- [ ] `npm run build`\n- [ ] {{any feature-specific manual verification, e.g. \"Verified Dashboard 用量页 cache hit card renders with mock data\"}}\n- [ ] {{`npm run test:real` if the change touches upstream protocol}}\n\n## Notes\n\n{{Optional. Use for any of:\n - Reviewer attention requests (\"please double-check the SSE buffer math in src/...\")\n - Known follow-ups (\"memory entry for new RT format will land in a separate PR\")\n - Migration / config impact (\"operators must add `update.allow_prerelease` if they want beta\")\n - Screenshots for UI changes\nRemove this section if there are no notes.}}\n\n## Linked Issues\n\n{{Closes #N / Refs #N — remove if none.}}\n",".agents/skills/pr-push/references/changelog-format.md":"# CHANGELOG Format\n\nCodex-proxy follows [Keep a Changelog](https://keepachangelog.com/). Every PR that changes user-visible behavior, public API, configuration, or build/release infrastructure MUST add an entry to `CHANGELOG.md` under `## [Unreleased]`.\n\n## Section Layout\n\n`## [Unreleased]` contains exactly these subsections (in this order, omit empty ones):\n\n```markdown\n## [Unreleased]\n\n### Changed\n\n- ...\n\n### Added\n\n- ...\n\n### Fixed\n\n- ...\n```\n\n| Subsection | Use for |\n|---|---|\n| `### Added` | New features, new endpoints, new config keys, new CLI flags |\n| `### Changed` | Behavior change of existing features, default value changes, signature changes |\n| `### Fixed` | Bug fixes |\n| `### Removed` | Deleted features (rare; gate behind a deprecation cycle first) |\n| `### Deprecated` | Marking something for future removal |\n| `### Security` | Security-relevant fix (CVE, cred leak, etc.) |\n\n## Entry Style\n\n- Use the same language as the existing `[Unreleased]` entries (zh-CN at time of writing). If the file flips to English, follow.\n- Lead with the user-visible impact, then mention the file paths in parentheses for reviewer navigation.\n- Reference issues / PRs with `(#NNN)` inline.\n- Multi-aspect entries get nested bullets.\n\n## Examples (from current `[Unreleased]`)\n\n```markdown\n### Added\n\n- 图像生成请求计数（成功 / 失败分流）：`AccountUsage` 新增 `image_request_count` / `image_request_failed_count`...\n- Dashboard 用量统计新增「缓存命中率」卡片...\n```\n\n```markdown\n### Changed\n\n- `bump-electron-beta.yml` 触发改为定时 cron（每天 04:00 / 12:00 UTC）...\n```\n\n## When NOT to add a CHANGELOG entry\n\nSkip CHANGELOG for commits that are:\n\n- Test-only (`test:` prefix) — no user impact\n- Doc-only edits to internal docs (`CLAUDE.md`, `.claude/`, `docs/dev-notes/`)\n- Pure refactors that change zero observed behavior (`refactor:` prefix with no API surface change)\n- CI-only changes that do not affect built artifacts (`ci:` prefix)\n- Style/formatting (`style:` prefix)\n\nIf unsure, **add the entry**. A redundant entry is cheaper than a missing one.\n\n## Multi-line / multi-bullet entries\n\nUse the existing nested bullet pattern:\n\n```markdown\n- Ollama bridge cleanup (#403 review followups, closes #405 #406 #407):\n  - `src/ollama/bridge.ts` 不再重复实现 `normalizeHostname`...\n  - `proxyOpenAIRequest` 转发头扩展到...\n  - `MAX_SSE_BUFFER` 重命名为 `MAX_SSE_BUFFER_CHARS`...\n```\n",".agents/skills/pr-push/references/commit-conventions.md":"# Commit Message Conventions\n\nCodex-proxy uses Conventional Commits with a fixed type vocabulary. Several CI workflows pattern-match on the type prefix, so unknown types break automation.\n\n## Format\n\n```\n<type>(<optional scope>): <imperative summary>\n\n<optional body — wrap at ~72 cols, explain WHY>\n\n<optional footer — Closes #N, Refs #N, BREAKING CHANGE: ...>\n```\n\n- Subject is **imperative mood**, lowercase first letter, no trailing period.\n- Subject ≤ 72 chars hard cap.\n- Body explains *why* the change was made, not *what* (the diff shows what).\n\n## Type Vocabulary\n\n| Type | Use for | Triggers beta release? |\n|---|---|---|\n| `feat` | New user-visible feature | yes |\n| `fix` | Bug fix | yes |\n| `perf` | Performance improvement with no behavior change | yes |\n| `refactor` | Code restructuring with no behavior change | no |\n| `docs` | Documentation only | no |\n| `test` | Test-only changes | no |\n| `chore` | Tooling, dependencies, repo housekeeping | no |\n| `ci` | CI/CD configuration | no |\n| `style` | Formatting, whitespace, no logic change | no |\n\nThe \"Triggers beta release?\" column is determined by `bump-electron-beta.yml`'s skip filter: `^(chore|docs|ci|test|refactor|style)`. Note that `fix(ci):` still triggers a beta release because the prefix is `fix`.\n\n## Scope\n\nOptional, but encouraged for clarity. Use the top-level module name:\n\n- `feat(auth): ...`\n- `fix(translation): ...`\n- `refactor(routes): ...`\n- `chore(deps): ...`\n- `ci(release): ...`\n\nSkip the scope when the change spans multiple modules or is genuinely repo-wide.\n\n## Examples\n\nGood:\n\n```\nfeat(auth): persist account-pool RT-only imports across restarts\n```\n\n```\nfix(translation): recover from previous_response_not_found instead of passing it through\n```\n\n```\nrefactor(routes): extract shared proxy-handler from openai/anthropic/gemini handlers\n```\n\nBad — and why:\n\n| Message | Why it fails |\n|---|---|\n| `Update auth.ts` | No type, describes WHAT not WHY |\n| `feat: Added new feature.` | Past tense + capitalized + trailing period |\n| `feature(auth): persist RT` | `feature` is not in the vocabulary, use `feat` |\n| `fix: stuff` | Subject is meaningless |\n| `wip` | No type, no information |\n\n## Multi-line body\n\nUse a HEREDOC to preserve formatting:\n\n```bash\ngit commit -m \"$(cat <<'EOF'\nfix(quota): ignore stale x-codex-* headers after token refresh\n\nThe previous behavior overwrote fresh quota state with cached headers\nfrom the old token, causing accounts to appear over-quota for ~30s\nafter refresh. Now we drop quota updates whose token id does not match\nthe current session.\n\nCloses #418\nEOF\n)\"\n```\n",".agents/skills/pr-push/references/pr-checklist.md":"# Pre-PR Self-Check\n\nWalk this list before opening the PR. Anything left unchecked needs a written reason in the PR body.\n\n## Branch & target\n\n- [ ] Current branch is NOT `dev` or `main`\n- [ ] Branch is rebased on (or fast-forwardable to) `origin/dev`\n- [ ] PR target = `dev`\n\n## Commit hygiene\n\n- [ ] Each commit follows `<type>(<scope>): <summary>` with a vocabulary type (see `commit-conventions.md`)\n- [ ] No commit was created with `--no-verify`\n- [ ] No file added with `git add -f`\n- [ ] No accidental staging of `node_modules/`, `dist/`, `*.log`, `.env*`, `data/`, or other gitignored paths\n- [ ] No secrets in code or commit messages (API keys, tokens, cookies, oauth_state)\n\n## CHANGELOG\n\n- [ ] If the change touches `src/`, `shared/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` → `CHANGELOG.md` `[Unreleased]` has a new entry\n- [ ] Entry placed in correct subsection (Added / Changed / Fixed)\n- [ ] Entry references the issue / PR number when applicable\n\n## Cross-artifact impact\n\nCodex-proxy ships three artifacts: backend (Docker), Electron desktop, web frontend. The pre-push hook will catch most of these, but verify mentally first:\n\n- [ ] If `src/` changed → backend logic still passes `npm test`\n- [ ] If `web/` changed → `npm run build` produces a clean Vite bundle\n- [ ] If `Dockerfile` / `docker-compose*` changed → image still builds\n- [ ] If `packages/electron/**` or `electron-builder.yml` changed → Electron config validates\n- [ ] If `native/**` changed → native addon still builds\n\n## Tests\n\n- [ ] New behavior has new tests (TDD: tests written first when feasible)\n- [ ] All affected `npm test` suites pass locally\n- [ ] No `*.skip` left behind unless explicitly justified in the PR body\n\n## TypeScript\n\n- [ ] No `any`, `as any`, `: any`, or `<any>` in new code (use `unknown`, generics, or specific types)\n- [ ] No `@ts-ignore` / `@ts-expect-error` without an inline explanation comment\n\n## Real-upstream changes\n\n- [ ] If the change touches the upstream protocol (translation/, proxy/, auth/), `npm run test:real` was attempted at least once\n\n## Documentation\n\n- [ ] Public-facing config/flag changes are reflected in `config/default.yaml` comments and `CLAUDE.md` if relevant\n- [ ] No internal personal notes leaked into committed files\n\n## After push (do NOT do these in this skill)\n\n- [ ] Wait for CI green before requesting review\n- [ ] Merge is a separate, explicit decision — never auto-merge from this skill\n",".claude/skills/issue-create/SKILL.md":"---\nname: issue-create\ndescription: >-\n  Interview the user to gather all required context, then open a high-quality GitHub issue (`gh issue create`) on the codex-proxy repo with the right template, labels, and structured body.\n  TRIGGER when: user says \"open an issue\", \"file an issue\", \"create issue\", \"report a bug\", \"feature request\", \"提个 issue\", \"报 bug\", \"提需求\".\n  DO NOT TRIGGER when: user wants to view, search, comment on, or close existing issues (use `gh issue list/view/comment/close` directly); user is writing a PR description (use `pr-push`).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Write\"\n---\n\n# Issue Create\n\nGather complete context through a structured interview, then file a well-formed issue. The interview is a hard gate — vague issues waste maintainer time.\n\n## Overview\n\nMost \"I have a bug\" or \"I want a feature\" reports are missing the information a maintainer needs to act. This skill runs a four-phase interview, fills the appropriate template, applies the right labels, and only then calls `gh issue create`. The user sees and approves the rendered body before submission.\n\n## When to Use\n\n- A user wants to file a new issue on the codex-proxy repository.\n- A user describes a bug or feature in conversation and asks \"should we file an issue?\"\n\n## Important Rules\n\n1. **The interview is not optional.** Do NOT call `gh issue create` until all required fields for the chosen type are collected and the user has explicitly approved the rendered body.\n2. **Never invent reproduction steps, version numbers, log output, or behavior.** If the user did not provide it, ask. If they cannot provide it, write \"not provided\" in the field, do not fabricate.\n3. **Show the full body before submitting.** The user must explicitly say \"submit\" / \"looks good\" / equivalent. \"Yes\" without seeing the body is not enough — show it first.\n4. **Apply only labels from the project's existing label set.** Read `references/labels.md` for the catalog. Do not invent new labels.\n5. **Strip secrets.** If the user pastes logs, headers, or config that contain tokens, cookies, OAuth state, API keys, or account IDs, redact them before they enter the issue body. Replace with `<redacted>`.\n6. **One issue per scope.** If the user describes two unrelated problems, file two issues. Ask before splitting.\n\n## Key Workflows\n\n### Phase 1: Type classification\n\n**Goal:** Pick the right template and label.\n\nAsk the user (one consolidated question):\n\n> What type of issue is this?\n>   1. **Bug** — something is broken or behaves incorrectly\n>   2. **Feature request** — propose new functionality\n>   3. **Question** — usage / configuration / \"is this expected?\"\n>   4. **Performance** — measurable regression or slowness\n>   5. **Documentation** — docs are wrong, missing, or unclear\n\nRead the type spec:\n```\nRead: .claude/skills/issue-create/references/issue-types.md\n```\n\nMap answer to template path:\n\n| Type | Template asset | Default label |\n|---|---|---|\n| Bug | `assets/bug-report.md` | `bug` |\n| Feature request | `assets/feature-request.md` | `enhancement` |\n| Question | `assets/question.md` | `question` |\n| Performance | `assets/perf-report.md` | `bug` |\n| Documentation | `assets/feature-request.md` (with docs framing) | `documentation` |\n\nDo **NOT** proceed to Phase 2 until the type is confirmed.\n\n### Phase 2: Required-field interview\n\n**Goal:** Collect every field the chosen template requires.\n\nRead `references/issue-types.md` to see the required-field table for the chosen type. Ask for missing fields in **one consolidated message**, not one at a time. Group related fields together.\n\n**For bugs**, the required fields are:\n- One-line summary\n- Expected behavior\n- Actual behavior\n- Reproduction steps (numbered)\n- Codex-proxy version (`npm pkg get version` or app About dialog)\n- Deployment mode (Electron app / Docker / `npm start` / dev)\n- Relevant log lines (redact secrets)\n- Frequency (always / intermittent / once)\n\n**For feature requests**, the required fields are:\n- Problem the feature solves (user-facing motivation, not the proposed solution)\n- Proposed solution (high level)\n- Alternatives considered\n- Who benefits (single user / all users / specific deployment mode)\n\n**For questions**:\n- What you tried\n- What you expected\n- What happened\n- Relevant config (redact secrets)\n\n**For performance**:\n- All bug fields, plus:\n- Measured baseline vs current (timings, memory, request count — be specific)\n- Reproduction harness (script, steps, or `tests/bench/`)\n\n**For documentation**:\n- Which doc page / file\n- What is wrong or missing\n- Suggested fix (if any)\n\nIf a field cannot be answered, the user must explicitly say \"not applicable\" or \"unknown\" — record that verbatim. Do not silently skip.\n\nDo **NOT** proceed to Phase 3 until every required field has either an answer or an explicit \"not applicable\".\n\n### Phase 3: Code & related-context grounding\n\n**Goal:** Help maintainers find the relevant code fast.\n\nAsk the user for:\n- File paths or `file:line` references they suspect are involved (optional but encouraged).\n- Related issues / PRs to link (`Refs #N`, `Related to #N`).\n- Whether they tried searching existing issues (`gh issue list --search \"<keywords>\"`). If they have not and the report sounds like something that might exist, run the search and show top 3 matches before continuing.\n\nIf the user provides no code locations and the bug is concrete, optionally offer:\n> \"Want me to grep for the relevant code so we can include file:line in the issue?\"\n\nDo not grep silently — ask first, and only do it once.\n\n### Phase 4: Render, confirm, submit\n\n**Goal:** Show the final body, get explicit approval, file the issue.\n\n1. Read the chosen template:\n   ```\n   Read: .claude/skills/issue-create/assets/<template>.md\n   ```\n2. Read the labels catalog:\n   ```\n   Read: .claude/skills/issue-create/references/labels.md\n   ```\n3. Fill the template with the collected fields. Strip secrets per Important Rule #5.\n4. Pick labels:\n   - Always include the type label (Phase 1 mapping).\n   - Add `good first issue` only if the user explicitly says it qualifies (small scope, low context required).\n   - Add `help wanted` if the user has no plan to fix it themselves.\n   - Add `documentation` in addition to the type label if docs need updating.\n5. Show the user the complete rendered output:\n   ```\n   Title: <title>\n   Labels: <label1>, <label2>\n   Body:\n   <full body>\n   ```\n6. Ask: \"Ready to submit, or want to adjust anything?\"\n7. Wait for an explicit affirmative. \"Yes\", \"submit\", \"go\", \"looks good\", \"提交\" all qualify. Silence or hedging does not.\n8. Submit:\n   ```bash\n   gh issue create \\\n     --title \"<title>\" \\\n     --label \"<label1>,<label2>\" \\\n     --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n9. Print the issue URL.\n10. **STOP.** Do not assign, do not comment, do not link to projects unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not call `gh issue create` before showing the body for approval.\n- Do not invent reproduction steps when the user gave a vague report — ask.\n- Do not paste raw logs that contain tokens / cookies / OAuth state / account IDs.\n- Do not apply labels outside the existing catalog.\n- Do not file two issues from one report without confirming the split with the user.\n- Do not grep / search the codebase silently to \"fill in\" missing fields — ask first.\n",".claude/skills/issue-create/assets/bug-report.md":"<!--\nBug report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nMatch the language of the repo's existing issues (currently a mix of zh-CN and en).\n-->\n\n## Summary\n\n{{One sentence describing the bug.}}\n\n## Expected behavior\n\n{{What the user thought would happen.}}\n\n## Actual behavior\n\n{{What actually happened.}}\n\n## Reproduction steps\n\n1. {{step 1}}\n2. {{step 2}}\n3. {{step 3 — describe the failure}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| Frequency | {{always / intermittent / once}} |\n| First broken version (if known) | {{version or \"unknown\"}} |\n| Workaround (if any) | {{description or \"none\"}} |\n\n## Logs / output\n\n```\n{{Paste relevant log lines. SECRETS REDACTED — no tokens, cookies,\noauth_state, API keys, account IDs.}}\n```\n\n## Additional context\n\n{{Anything else the maintainer should know. Remove this section if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n",".claude/skills/issue-create/assets/feature-request.md":"<!--\nFeature request template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\n-->\n\n## Summary\n\n{{One sentence describing the feature.}}\n\n## Problem\n\n{{The user-facing motivation. What can the user not do today, or what is\npainful about how they have to do it? DO NOT describe the proposed\nsolution here — only the problem.}}\n\n## Proposed solution\n\n{{High-level description of how the feature would work. Implementation\ndetail is welcome but not required. If you have a UI in mind, sketch\nor screenshot helps.}}\n\n## Alternatives considered\n\n{{Other approaches the user thought about and why they don't fit.\nEven \"I considered X but it doesn't work because Y\" is useful — it\nsaves the maintainer from re-deriving the same conclusion.}}\n\n## Who benefits\n\n{{single user / all users / a specific deployment mode (Electron / Docker / dev) /\na specific upstream provider / a specific account state}}\n\n## Impact if not done\n\n{{Does the user have a workaround? Is this blocking? Nice-to-have?\nRemove this section if \"no impact, just nice\".}}\n\n## Additional context\n\n{{Mockups, links, related discussions. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n",".claude/skills/issue-create/assets/perf-report.md":"<!--\nPerformance report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nA perf report without numbers is just a bug — switch to bug-report.md if\nno measurements are available.\n-->\n\n## Summary\n\n{{One sentence describing the regression or slowness.}}\n\n## Expected behavior\n\n{{What performance was expected, and where that expectation comes from\n(prior version, docs, comparable system).}}\n\n## Actual behavior\n\n{{What is observed instead.}}\n\n## Measurements\n\n| Metric | Baseline | Current | Delta |\n|---|---|---|---|\n| {{e.g. p95 latency}} | {{200ms}} | {{1.4s}} | {{+600%}} |\n| {{e.g. memory RSS}} | {{180MB}} | {{420MB}} | {{+133%}} |\n\n**Methodology:** {{How the numbers were taken — script, manual stopwatch,\nprofiler, load test. Be specific enough that a maintainer can reproduce.}}\n\n## Reproduction harness\n\n```\n{{Script, `tests/bench/...` reference, or numbered steps. Must be\ndeterministic enough to re-measure.}}\n```\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| First slow version (if known) | {{version or \"unknown\"}} |\n| Resource constraint hit | {{CPU / memory / network / FDs / \"none\"}} |\n\n## Logs / output\n\n```\n{{Relevant log lines or profiler output. SECRETS REDACTED.}}\n```\n\n## Additional context\n\n{{Anything else. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n",".claude/skills/issue-create/assets/question.md":"<!--\nQuestion template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nNote: if it turns out to be a bug, switch to the bug-report template.\n-->\n\n## What I'm trying to accomplish\n\n{{The end goal, not the immediate confusion. e.g. \"I want to route\ngpt-5.5 traffic only to my work account\" — not \"what does\nplan_mapping do?\"}}\n\n## What I tried\n\n{{Commands, config snippets, docs read, search terms used. Be specific.}}\n\n```yaml\n# Relevant config — SECRETS REDACTED\n{{config snippet or \"none\"}}\n```\n\n## What I expected\n\n{{What outcome did you anticipate?}}\n\n## What happened\n\n{{What did you actually observe?}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n\n## Additional context\n\n{{Logs, screenshots, anything else. Remove if empty.}}\n",".claude/skills/issue-create/references/issue-types.md":"# Issue Type Specs\n\nRequired and optional fields per issue type. The skill enforces \"required\" — every required field must have either an answer or an explicit \"not applicable\" / \"unknown\" before the issue can be filed.\n\n## Bug\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Becomes part of the title; ≤72 chars |\n| Expected behavior | yes | What the user thought would happen |\n| Actual behavior | yes | What actually happened |\n| Reproduction steps | yes | Numbered list, deterministic |\n| Codex-proxy version | yes | `npm pkg get version` or About dialog |\n| Deployment mode | yes | Electron / Docker / `npm start` / dev / source |\n| OS + arch | yes | e.g. macOS 14.5 arm64, Windows 11 x64, Ubuntu 22.04 x64 |\n| Relevant logs | yes | Redact secrets; \"none\" is acceptable |\n| Frequency | yes | always / intermittent / once |\n| Workaround | no | If the user found one |\n| First broken version | no | If known (helps bisect) |\n| Related issues | no | `Refs #N` |\n\n## Feature Request\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Title material |\n| Problem statement | yes | The user-facing motivation. NOT the proposed solution. |\n| Proposed solution | yes | High level; implementation detail is welcome but optional |\n| Alternatives considered | yes | Even \"I considered X but it doesn't fit because Y\" |\n| Who benefits | yes | single user / all users / specific deployment mode / specific upstream |\n| Impact if NOT done | no | Does the user have a workaround? Is this blocking? |\n| Related issues / PRs | no | `Refs #N` |\n| Mockups / sketches | no | For UI features |\n\n## Question\n\n| Field | Required | Notes |\n|---|---|---|\n| What you're trying to accomplish | yes | The end goal, not the immediate confusion |\n| What you tried | yes | Commands, config, links to docs read |\n| What you expected | yes | |\n| What happened | yes | |\n| Relevant config | yes | Redact secrets; \"none\" if no config involved |\n| Codex-proxy version | yes | |\n| Deployment mode | yes | |\n\nIf a \"question\" turns out to be a bug during the interview, switch to the Bug template — do not file under `question`.\n\n## Performance\n\nAll Bug fields, plus:\n\n| Field | Required | Notes |\n|---|---|---|\n| Baseline measurement | yes | Numbers from a known-good version or expected baseline |\n| Current measurement | yes | Same metric, current version |\n| Measurement methodology | yes | How the numbers were taken — script, manual stopwatch, profiler |\n| Reproduction harness | yes | Script, `tests/bench/...` reference, or steps |\n| Resource constraint hit | no | CPU, memory, network, file descriptors, etc. |\n\nA perf report without numbers is a bug report — switch templates.\n\n## Documentation\n\n| Field | Required | Notes |\n|---|---|---|\n| Doc location | yes | File path (`README.md`, `CLAUDE.md`, `docs/...`) or URL |\n| What is wrong / missing | yes | Specific quote of the offending text, or \"this section is missing\" |\n| Suggested fix | no | Welcome but not required |\n| Audience affected | no | New users / operators / contributors / API consumers |\n",".claude/skills/issue-create/references/labels.md":"# Issue Labels (codex-proxy)\n\nThe complete catalog of labels currently defined on the repo. Apply only labels from this list — do not invent new ones. To propose a new label, file a `chore:` issue separately.\n\n| Label | Color | Use for |\n|---|---|---|\n| `bug` | #d73a4a | Something isn't working as documented or intended |\n| `enhancement` | #a2eeef | New feature or extension of an existing feature |\n| `documentation` | #0075ca | Improvements or additions to documentation |\n| `question` | #d876e3 | Further information is requested; not yet known to be a bug |\n| `help wanted` | #008672 | Maintainers welcome contributors to take this on |\n| `good first issue` | #7057ff | Small scope, low context required, friendly to newcomers |\n| `duplicate` | #cfd3d7 | Already filed elsewhere — set after triage, not on creation |\n| `invalid` | #e4e669 | Not actionable or out of scope — set after triage |\n| `wontfix` | #ffffff | Acknowledged but will not be addressed — set after triage |\n| `sync-conflict` | #d73a4a | `master → electron` auto-sync merge conflict — used by automation, not for human-filed issues |\n\n## Application rules for the skill\n\n1. **One type label minimum**: bug / enhancement / documentation / question (pick exactly one based on the issue type).\n2. **`good first issue`**: only when the user explicitly confirms the scope is small AND the fix is local (single file or single module).\n3. **`help wanted`**: when the reporter has no plan to send a PR themselves.\n4. **`documentation`** can be combined with `bug` or `enhancement` if the change requires both code and doc updates.\n5. **Never apply on creation**: `duplicate`, `invalid`, `wontfix`, `sync-conflict`. These are triage / automation labels.\n\n## CLI form\n\n```bash\ngh issue create --label \"bug,help wanted\" ...\n```\n\nMultiple labels are comma-separated (no space after the comma).\n",".claude/skills/pr-push/SKILL.md":"---\nname: pr-push\ndescription: >-\n  Package the current working changes into a standards-compliant codex-proxy pull request:\n  branch hygiene, commit message linting, CHANGELOG prompt, conventional commit, push, and `gh pr create` against the `dev` branch.\n  TRIGGER when: user asks to \"push a PR\", \"open a PR\", \"create PR\", \"ship this\", \"推 PR\", \"开 PR\", \"提交 PR\".\n  DO NOT TRIGGER when: user only wants to commit without pushing; user explicitly wants to push directly to master/main; user wants to merge, rebase, or close an existing PR (use `gh pr merge` / `gh pr close` directly).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Edit\"\n  - \"Write\"\n  - \"Grep\"\n---\n\n# PR Push\n\nTurn the current working tree into a clean PR targeting `dev`. This skill enforces codex-proxy's contribution rules so community maintainers do not have to memorize them.\n\n## Overview\n\nCodex-proxy uses a `dev` → `master` promotion flow with strict commit conventions, CHANGELOG discipline, and a pre-push validation hook. This skill walks the maintainer through an interview, makes the commit, runs the push (letting the hook gate quality), and opens the PR. It explicitly stops before merge — review and merge are separate human decisions.\n\n## When to Use\n\n- A maintainer has finished a unit of work in their working tree and wants it on `dev`.\n- A maintainer asks to \"open a PR\" or equivalent and the working tree has changes (staged, unstaged, or untracked).\n\n## Important Rules\n\n1. **Target branch is always `dev`.** Never open a PR against `master` or `main` unless the user explicitly states \"target master\" with a written reason. The `master` branch is fast-forwarded by the `promote-dev-to-master.yml` workflow — manual PRs to `master` break that contract.\n2. **Never commit on `dev`, `master`, or `main` directly.** If `git branch --show-current` is one of these, stop and ask the user to name a feature branch (`git switch -c <name>`).\n3. **Never use `git add -A`, `git add .`, or `git add -f`.** Stage files by explicit path. `-f` overrides `.gitignore` and has been the cause of secret leaks elsewhere.\n4. **Never pass `--no-verify` to `git commit` or `git push`.** The hook is the gate. If it fails, fix the underlying issue, do not bypass.\n5. **Stop after `gh pr create`.** Do not merge, do not approve, do not enable auto-merge. Pushing a PR and merging a PR are two human decisions.\n6. **CHANGELOG gate.** If any file under `src/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` changed, `CHANGELOG.md`'s `[Unreleased]` section MUST have a new entry covering the change before the commit is created.\n7. **Commit message format is fixed:** `<type>(<optional-scope>): <imperative summary>`. The type set is enumerated in `references/commit-conventions.md`.\n\n## Key Workflows\n\n### Phase 1: Discovery (interview, do not touch the repo yet)\n\n**Goal:** Understand what is being shipped before any git operation.\n\nRun these read-only commands in parallel and summarize results back to the user:\n\n```\ngit branch --show-current\ngit status --short\ngit diff --stat\ngit log --oneline -10\n```\n\nThen read the conventions:\n```\nRead: .claude/skills/pr-push/references/commit-conventions.md\nRead: .claude/skills/pr-push/references/changelog-format.md\nRead: .claude/skills/pr-push/references/pr-checklist.md\n```\n\nAsk the user (in one consolidated message) for any field that cannot be inferred:\n\n- **Commit type** (feat / fix / refactor / docs / test / chore / perf / ci) — propose one based on the diff, ask for confirmation.\n- **One-line summary** (imperative, lowercase, no trailing period) — propose one based on the diff.\n- **PR target** — default `dev`. Confirm only if the user previously asked to deviate.\n- **CHANGELOG entry** — if the gate in Important Rules #6 applies and `CHANGELOG.md` `[Unreleased]` has no matching entry, ask the user to dictate one (or offer to draft one for review). Do not invent silently.\n- **Memory / docs touch** — if the change touches public protocol, request flow, auth lifecycle, or release infra, ask whether `CLAUDE.md` needs updating in the same PR.\n\nDo **NOT** proceed to Phase 2 until the user has explicitly confirmed (a) commit type, (b) summary, (c) CHANGELOG status, (d) target = `dev`.\n\n### Phase 2: Branch hygiene\n\n**Goal:** Make sure the commit lands on a feature branch, not on `dev`/`master`.\n\n1. Check `git branch --show-current`.\n2. If the current branch is `dev`, `master`, or `main`:\n   - Stop. Ask the user to provide a feature branch name (suggest one derived from the commit summary, kebab-case, ≤40 chars).\n   - Run `git switch -c <name>`. Do not auto-pick a name without confirmation.\n3. If the current branch is a feature branch but is not based on up-to-date `origin/dev`:\n   - Run `git fetch origin dev`.\n   - If `git merge-base --is-ancestor origin/dev HEAD` is false (branch is behind), warn the user and ask whether to `git rebase origin/dev` before continuing. Do not rebase silently.\n\n### Phase 3: Stage + commit\n\n**Goal:** Produce one well-formed commit.\n\n1. List the files the user wants in this commit. If they didn't say, propose the list from `git status --short` and confirm.\n2. Run `git add <file1> <file2> ...` with explicit paths. Never `-A`, `.`, or `-f`.\n3. If CHANGELOG was updated as part of Phase 1, include `CHANGELOG.md` in the staged set.\n4. Build the commit message:\n   - First line: `<type>(<scope>): <summary>` — scope is optional, omit parentheses if no scope.\n   - Body (optional): wrap at ~72 cols, explain *why*, reference issues with `Closes #N` / `Refs #N` if applicable.\n5. Commit with a HEREDOC (preserves formatting):\n   ```bash\n   git commit -m \"$(cat <<'EOF'\n   <type>(<scope>): <summary>\n\n   <optional body>\n   EOF\n   )\"\n   ```\n6. If the commit fails because of a pre-commit hook, fix the reported issue and create a NEW commit (do not `--amend`). Re-run the same command after fixes.\n\n### Phase 4: Push\n\n**Goal:** Get the branch to `origin` so a PR can be opened.\n\n1. Confirm the user wants to push (a single short \"ready to push?\" — they may have wanted to inspect the commit first).\n2. **Hook presence check.** The repo's pre-push gate lives at `.claude/hooks/pre-push-validate.sh`, which is gitignored — fresh clones do **not** have it. Run `test -x .claude/hooks/pre-push-validate.sh`:\n   - **Hook present** → push normally; the hook will run.\n   - **Hook missing** → warn the user that no pre-push gate is installed, then run the equivalent checks inline based on what the diff touched, before pushing:\n     | Diff touches | Run |\n     |---|---|\n     | `src/**` or `tests/**` | `npm test` and `npx tsc --noEmit` |\n     | `web/**` | `npm run build` |\n     | `Dockerfile`, `docker-compose*` | `docker build .` (or note user must verify) |\n     | `packages/electron/**`, `electron-builder.yml` | `npm run -w packages/electron build` |\n     | `native/**` | `npm run -w native build` |\n     Any failure aborts the push — fix and re-run.\n3. Run `git push -u origin HEAD`.\n4. If the push is blocked by the hook:\n   - Read the hook output verbatim back to the user.\n   - The hook validates the build targets affected by the diff (test, tsc, web build, Dockerfile lint, Electron config, native addon). Identify which target failed and propose a fix.\n   - **Never retry with `--no-verify`.** Re-run the offending check locally, fix the root cause, amend the commit only if the user authorizes it, otherwise add a fix-up commit.\n\n### Phase 5: Open the PR\n\n**Goal:** Create a PR against `dev` with a body that future reviewers can read cold.\n\n1. Read the PR body template:\n   ```\n   Read: .claude/skills/pr-push/assets/pr-body-template.md\n   ```\n2. Determine PR title:\n   - If the branch has a single commit, reuse the commit subject.\n   - If multiple commits, propose a title that summarizes the branch's intent and confirm with user.\n   - Title MUST start with a conventional type, MUST be ≤72 chars.\n3. Fill the body sections (Summary / Test Plan / Notes). Source content from:\n   - `git log <base>..HEAD` for the change list.\n   - The CHANGELOG entry the user wrote.\n   - Test commands actually run locally (do not invent test results).\n4. Show the rendered title + body to the user. **Wait for explicit \"looks good\" before invoking `gh`.**\n5. Create the PR:\n   ```bash\n   gh pr create --base dev --title \"<title>\" --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n6. Print the PR URL.\n7. **STOP.** Do not run `gh pr merge`, `gh pr review --approve`, `gh pr edit --add-label`, or `--auto-merge` unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not assume the user wants every modified file in the PR — ask.\n- Do not auto-write the CHANGELOG entry without showing it for approval first.\n- Do not retry a failing pre-push hook with `--no-verify`.\n- Do not open the PR against `master` even if the user is on a branch named `master-fix-X` — branch name does not imply target.\n- Do not silently rebase. If the branch needs rebase against `origin/dev`, ask first.\n- Do not chain `gh pr create` with `gh pr merge`. Two separate decisions.\n",".claude/skills/pr-push/assets/pr-body-template.md":"<!--\nPR body template for codex-proxy. The skill fills in the {{placeholders}}\nand removes optional sections that don't apply. Default language follows\nthe repo's dominant language (currently zh-CN for CHANGELOG entries,\nen for code/commits). Pick one and stay consistent within a single PR.\n-->\n\n## Summary\n\n{{One paragraph: WHAT changed and WHY. Reference the user-visible impact.\nIf multiple commits, summarize the branch's intent, not each commit.}}\n\n## Changes\n\n{{Bulleted list mirroring the CHANGELOG entry. Group by area when the PR\ntouches multiple modules. Reference file paths so reviewers can navigate.}}\n\n- {{change 1 — files}}\n- {{change 2 — files}}\n\n## Test Plan\n\n{{List the commands actually run locally. Do not invent results.\nMark checked items with [x], unchecked with [ ].}}\n\n- [ ] `npm test`\n- [ ] `npm run build`\n- [ ] {{any feature-specific manual verification, e.g. \"Verified Dashboard 用量页 cache hit card renders with mock data\"}}\n- [ ] {{`npm run test:real` if the change touches upstream protocol}}\n\n## Notes\n\n{{Optional. Use for any of:\n - Reviewer attention requests (\"please double-check the SSE buffer math in src/...\")\n - Known follow-ups (\"memory entry for new RT format will land in a separate PR\")\n - Migration / config impact (\"operators must add `update.allow_prerelease` if they want beta\")\n - Screenshots for UI changes\nRemove this section if there are no notes.}}\n\n## Linked Issues\n\n{{Closes #N / Refs #N — remove if none.}}\n",".claude/skills/pr-push/references/changelog-format.md":"# CHANGELOG Format\n\nCodex-proxy follows [Keep a Changelog](https://keepachangelog.com/). Every PR that changes user-visible behavior, public API, configuration, or build/release infrastructure MUST add an entry to `CHANGELOG.md` under `## [Unreleased]`.\n\n## Section Layout\n\n`## [Unreleased]` contains exactly these subsections (in this order, omit empty ones):\n\n```markdown\n## [Unreleased]\n\n### Changed\n\n- ...\n\n### Added\n\n- ...\n\n### Fixed\n\n- ...\n```\n\n| Subsection | Use for |\n|---|---|\n| `### Added` | New features, new endpoints, new config keys, new CLI flags |\n| `### Changed` | Behavior change of existing features, default value changes, signature changes |\n| `### Fixed` | Bug fixes |\n| `### Removed` | Deleted features (rare; gate behind a deprecation cycle first) |\n| `### Deprecated` | Marking something for future removal |\n| `### Security` | Security-relevant fix (CVE, cred leak, etc.) |\n\n## Entry Style\n\n- Use the same language as the existing `[Unreleased]` entries (zh-CN at time of writing). If the file flips to English, follow.\n- Lead with the user-visible impact, then mention the file paths in parentheses for reviewer navigation.\n- Reference issues / PRs with `(#NNN)` inline.\n- Multi-aspect entries get nested bullets.\n\n## Examples (from current `[Unreleased]`)\n\n```markdown\n### Added\n\n- 图像生成请求计数（成功 / 失败分流）：`AccountUsage` 新增 `image_request_count` / `image_request_failed_count`...\n- Dashboard 用量统计新增「缓存命中率」卡片...\n```\n\n```markdown\n### Changed\n\n- `bump-electron-beta.yml` 触发改为定时 cron（每天 04:00 / 12:00 UTC）...\n```\n\n## When NOT to add a CHANGELOG entry\n\nSkip CHANGELOG for commits that are:\n\n- Test-only (`test:` prefix) — no user impact\n- Doc-only edits to internal docs (`CLAUDE.md`, `.claude/`, `docs/dev-notes/`)\n- Pure refactors that change zero observed behavior (`refactor:` prefix with no API surface change)\n- CI-only changes that do not affect built artifacts (`ci:` prefix)\n- Style/formatting (`style:` prefix)\n\nIf unsure, **add the entry**. A redundant entry is cheaper than a missing one.\n\n## Multi-line / multi-bullet entries\n\nUse the existing nested bullet pattern:\n\n```markdown\n- Ollama bridge cleanup (#403 review followups, closes #405 #406 #407):\n  - `src/ollama/bridge.ts` 不再重复实现 `normalizeHostname`...\n  - `proxyOpenAIRequest` 转发头扩展到...\n  - `MAX_SSE_BUFFER` 重命名为 `MAX_SSE_BUFFER_CHARS`...\n```\n",".claude/skills/pr-push/references/commit-conventions.md":"# Commit Message Conventions\n\nCodex-proxy uses Conventional Commits with a fixed type vocabulary. Several CI workflows pattern-match on the type prefix, so unknown types break automation.\n\n## Format\n\n```\n<type>(<optional scope>): <imperative summary>\n\n<optional body — wrap at ~72 cols, explain WHY>\n\n<optional footer — Closes #N, Refs #N, BREAKING CHANGE: ...>\n```\n\n- Subject is **imperative mood**, lowercase first letter, no trailing period.\n- Subject ≤ 72 chars hard cap.\n- Body explains *why* the change was made, not *what* (the diff shows what).\n\n## Type Vocabulary\n\n| Type | Use for | Triggers beta release? |\n|---|---|---|\n| `feat` | New user-visible feature | yes |\n| `fix` | Bug fix | yes |\n| `perf` | Performance improvement with no behavior change | yes |\n| `refactor` | Code restructuring with no behavior change | no |\n| `docs` | Documentation only | no |\n| `test` | Test-only changes | no |\n| `chore` | Tooling, dependencies, repo housekeeping | no |\n| `ci` | CI/CD configuration | no |\n| `style` | Formatting, whitespace, no logic change | no |\n\nThe \"Triggers beta release?\" column is determined by `bump-electron-beta.yml`'s skip filter: `^(chore|docs|ci|test|refactor|style)`. Note that `fix(ci):` still triggers a beta release because the prefix is `fix`.\n\n## Scope\n\nOptional, but encouraged for clarity. Use the top-level module name:\n\n- `feat(auth): ...`\n- `fix(translation): ...`\n- `refactor(routes): ...`\n- `chore(deps): ...`\n- `ci(release): ...`\n\nSkip the scope when the change spans multiple modules or is genuinely repo-wide.\n\n## Examples\n\nGood:\n\n```\nfeat(auth): persist account-pool RT-only imports across restarts\n```\n\n```\nfix(translation): recover from previous_response_not_found instead of passing it through\n```\n\n```\nrefactor(routes): extract shared proxy-handler from openai/anthropic/gemini handlers\n```\n\nBad — and why:\n\n| Message | Why it fails |\n|---|---|\n| `Update auth.ts` | No type, describes WHAT not WHY |\n| `feat: Added new feature.` | Past tense + capitalized + trailing period |\n| `feature(auth): persist RT` | `feature` is not in the vocabulary, use `feat` |\n| `fix: stuff` | Subject is meaningless |\n| `wip` | No type, no information |\n\n## Multi-line body\n\nUse a HEREDOC to preserve formatting:\n\n```bash\ngit commit -m \"$(cat <<'EOF'\nfix(quota): ignore stale x-codex-* headers after token refresh\n\nThe previous behavior overwrote fresh quota state with cached headers\nfrom the old token, causing accounts to appear over-quota for ~30s\nafter refresh. Now we drop quota updates whose token id does not match\nthe current session.\n\nCloses #418\nEOF\n)\"\n```\n",".claude/skills/pr-push/references/pr-checklist.md":"# Pre-PR Self-Check\n\nWalk this list before opening the PR. Anything left unchecked needs a written reason in the PR body.\n\n## Branch & target\n\n- [ ] Current branch is NOT `dev`, `master`, or `main`\n- [ ] Branch is rebased on (or fast-forwardable to) `origin/dev`\n- [ ] PR target = `dev`\n\n## Commit hygiene\n\n- [ ] Each commit follows `<type>(<scope>): <summary>` with a vocabulary type (see `commit-conventions.md`)\n- [ ] No commit was created with `--no-verify`\n- [ ] No file added with `git add -f`\n- [ ] No accidental staging of `node_modules/`, `dist/`, `*.log`, `.env*`, `data/`, or other gitignored paths\n- [ ] No secrets in code or commit messages (API keys, tokens, cookies, oauth_state)\n\n## CHANGELOG\n\n- [ ] If the change touches `src/`, `shared/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` → `CHANGELOG.md` `[Unreleased]` has a new entry\n- [ ] Entry placed in correct subsection (Added / Changed / Fixed)\n- [ ] Entry references the issue / PR number when applicable\n\n## Cross-artifact impact\n\nCodex-proxy ships three artifacts: backend (Docker), Electron desktop, web frontend. The pre-push hook will catch most of these, but verify mentally first:\n\n- [ ] If `src/` changed → backend logic still passes `npm test`\n- [ ] If `web/` changed → `npm run build` produces a clean Vite bundle\n- [ ] If `Dockerfile` / `docker-compose*` changed → image still builds\n- [ ] If `packages/electron/**` or `electron-builder.yml` changed → Electron config validates\n- [ ] If `native/**` changed → native addon still builds\n\n## Tests\n\n- [ ] New behavior has new tests (TDD: tests written first when feasible)\n- [ ] All affected `npm test` suites pass locally\n- [ ] No `*.skip` left behind unless explicitly justified in the PR body\n\n## TypeScript\n\n- [ ] No `any`, `as any`, `: any`, or `<any>` in new code (use `unknown`, generics, or specific types)\n- [ ] No `@ts-ignore` / `@ts-expect-error` without an inline explanation comment\n\n## Real-upstream changes\n\n- [ ] If the change touches the upstream protocol (translation/, proxy/, auth/), `npm run test:real` was attempted at least once\n\n## Documentation\n\n- [ ] Public-facing config/flag changes are reflected in `config/default.yaml` comments and `CLAUDE.md` if relevant\n- [ ] No internal personal notes leaked into committed files\n\n## After push (do NOT do these in this skill)\n\n- [ ] Wait for CI green before requesting review\n- [ ] Merge is a separate, explicit decision — never auto-merge from this skill\n","AGENTS.md":"## 多 Agent 工作流\n\n- 仅在用户明确授权或任务明确要求时启用；完整规则见 `docs/MULTI_AGENT_WORKFLOW.md`。\n- 默认在满足最低安全和验收要求的前提下，优先减少总 token、credits、费用与重复阅读。\n- 开工前按语义难度、修改范围、可验证性、失败后果和上下文负担预分类。\n- 使用预计可完成任务的最低成本执行体；高性能执行体只用于关键推理、弱机械验收或高后果节点。\n- 简单任务不为使用多 Agent 增加调度成本；并行优先用于互不重叠的只读工作。\n- 同一工作树和合同域保持单写者；Reviewer/Verifier 默认只读。\n- 子 Agent 使用最小上下文、稳定公共前缀与增量证据，避免完整历史复制和重复读取。\n- 多 Agent 授权不扩大网络、真实 API、外部写入、提交、发布或破坏性操作权限。\n- 达到当前任务验收或停止条件后立即停止，不自动进入下一票据。\n\n## Gemini / Antigravity Schema 与日志\n\n- Gemini / Antigravity 的工具参数及结构化输出 schema 必须按 Gemini 支持的字段白名单清洗；清除 `prefixItems` 等不支持字段后，如果 schema 仍为 `type: array` 且缺少 `items`，需补宽松的 `{}` schema，避免 Gemini 的 `missing field` 校验错误。为此类变换补充嵌套 schema 回归测试。\n- 持久化请求/错误诊断时，必须先脱敏并限制单条记录和文件大小；不要提交临时的原始 tools / request dump，也不要记录凭据。\n\n## Keepalive safety\n\n- Account keepalive is disabled by default. Enabling the scheduler or calling `POST /admin/keepalive-run` sends real requests to `/codex/usage`; unit tests must mock `CodexApi`, and real-account execution requires explicit user authorization.\n","packages/npm/README.md":"# @icebear0828/codex-proxy\n\nOpenAI-compatible proxy for the ChatGPT Codex Responses API, with a web dashboard, a multi-account key pool and an Ollama-compatible bridge. This is the full application — dashboard, account management and the Ollama bridge all work the same as the desktop and Docker versions.\n\n## Install\n\nRequires Node.js 22.13+ (uses the built-in `node:sqlite`).\n\nThis package is published to GitHub Packages, not to the public npmjs registry. Installing it from GitHub Packages needs an npm auth token with `read:packages`:\n\n```ini\n@icebear0828:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\n```\n\n```bash\nnpm install -g @icebear0828/codex-proxy\n```\n\nNo-auth alternative: download `codex-proxy-npm.zip` from the [latest release](https://github.com/icebear0828/codex-proxy/releases/latest/download/codex-proxy-npm.zip), extract it and run `node install.mjs` inside the extracted directory.\n\n## Run\n\n```bash\ncodex-proxy            # starts the server and opens the dashboard\ncodex-proxy --mode=server   # headless server only\ncodex-proxy --mode=browser  # force the system browser\ncodex-proxy --help          # all options\n```\n\nOn first start the dashboard opens at `http://127.0.0.1:8080` (port configurable via `--port` or `PORT`). On Windows the dashboard opens in your system browser; the desktop app and the Lite zip ship a native WebView2 host, which the npm package does not include.\n\nRuntime data (accounts, config, usage history) is stored in the per-user data directory (`%APPDATA%\\@codex-proxy\\electron\\data` on Windows, `~/.config/@codex-proxy/electron/data` on Linux, `~/Library/Application Support/@codex-proxy/electron/data` on macOS), so it survives package updates. Set `CODEX_PROXY_DATA_DIR` or pass `--portable` to relocate it. Platform-specific TLS addons are installed automatically for your OS/architecture; binaries for other platforms are never downloaded.\n\n## Links\n\n- [GitHub repository](https://github.com/icebear0828/codex-proxy)\n- [Documentation & screenshots](https://github.com/icebear0828/codex-proxy#readme)\n- Desktop installers, the portable zip and Docker images are published on the [releases page](https://github.com/icebear0828/codex-proxy/releases).\n\n## License\n\nNon-commercial licence — see [LICENCE](https://github.com/icebear0828/codex-proxy/blob/dev/LICENCE).\n"},"files":{".agents/skills/issue-create/SKILL.md":"---\nname: issue-create\ndescription: >-\n  Interview the user to gather all required context, then open a high-quality GitHub issue (`gh issue create`) on the codex-proxy repo with the right template, labels, and structured body.\n  TRIGGER when: user says \"open an issue\", \"file an issue\", \"create issue\", \"report a bug\", \"feature request\", \"提个 issue\", \"报 bug\", \"提需求\".\n  DO NOT TRIGGER when: user wants to view, search, comment on, or close existing issues (use `gh issue list/view/comment/close` directly); user is writing a PR description (use `pr-push`).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Write\"\n---\n\n# Issue Create\n\nGather complete context through a structured interview, then file a well-formed issue. The interview is a hard gate — vague issues waste maintainer time.\n\n## Overview\n\nMost \"I have a bug\" or \"I want a feature\" reports are missing the information a maintainer needs to act. This skill runs a four-phase interview, fills the appropriate template, applies the right labels, and only then calls `gh issue create`. The user sees and approves the rendered body before submission.\n\n## When to Use\n\n- A user wants to file a new issue on the codex-proxy repository.\n- A user describes a bug or feature in conversation and asks \"should we file an issue?\"\n\n## Important Rules\n\n1. **The interview is not optional.** Do NOT call `gh issue create` until all required fields for the chosen type are collected and the user has explicitly approved the rendered body.\n2. **Never invent reproduction steps, version numbers, log output, or behavior.** If the user did not provide it, ask. If they cannot provide it, write \"not provided\" in the field, do not fabricate.\n3. **Show the full body before submitting.** The user must explicitly say \"submit\" / \"looks good\" / equivalent. \"Yes\" without seeing the body is not enough — show it first.\n4. **Apply only labels from the project's existing label set.** Read `references/labels.md` for the catalog. Do not invent new labels.\n5. **Strip secrets.** If the user pastes logs, headers, or config that contain tokens, cookies, OAuth state, API keys, or account IDs, redact them before they enter the issue body. Replace with `<redacted>`.\n6. **One issue per scope.** If the user describes two unrelated problems, file two issues. Ask before splitting.\n\n## Key Workflows\n\n### Phase 1: Type classification\n\n**Goal:** Pick the right template and label.\n\nAsk the user (one consolidated question):\n\n> What type of issue is this?\n>   1. **Bug** — something is broken or behaves incorrectly\n>   2. **Feature request** — propose new functionality\n>   3. **Question** — usage / configuration / \"is this expected?\"\n>   4. **Performance** — measurable regression or slowness\n>   5. **Documentation** — docs are wrong, missing, or unclear\n\nRead the type spec:\n```\nRead: .Codex/skills/issue-create/references/issue-types.md\n```\n\nMap answer to template path:\n\n| Type | Template asset | Default label |\n|---|---|---|\n| Bug | `assets/bug-report.md` | `bug` |\n| Feature request | `assets/feature-request.md` | `enhancement` |\n| Question | `assets/question.md` | `question` |\n| Performance | `assets/perf-report.md` | `bug` |\n| Documentation | `assets/feature-request.md` (with docs framing) | `documentation` |\n\nDo **NOT** proceed to Phase 2 until the type is confirmed.\n\n### Phase 2: Required-field interview\n\n**Goal:** Collect every field the chosen template requires.\n\nRead `references/issue-types.md` to see the required-field table for the chosen type. Ask for missing fields in **one consolidated message**, not one at a time. Group related fields together.\n\n**For bugs**, the required fields are:\n- One-line summary\n- Expected behavior\n- Actual behavior\n- Reproduction steps (numbered)\n- Codex-proxy version (`npm pkg get version` or app About dialog)\n- Deployment mode (Electron app / Docker / `npm start` / dev)\n- Relevant log lines (redact secrets)\n- Frequency (always / intermittent / once)\n\n**For feature requests**, the required fields are:\n- Problem the feature solves (user-facing motivation, not the proposed solution)\n- Proposed solution (high level)\n- Alternatives considered\n- Who benefits (single user / all users / specific deployment mode)\n\n**For questions**:\n- What you tried\n- What you expected\n- What happened\n- Relevant config (redact secrets)\n\n**For performance**:\n- All bug fields, plus:\n- Measured baseline vs current (timings, memory, request count — be specific)\n- Reproduction harness (script, steps, or `tests/bench/`)\n\n**For documentation**:\n- Which doc page / file\n- What is wrong or missing\n- Suggested fix (if any)\n\nIf a field cannot be answered, the user must explicitly say \"not applicable\" or \"unknown\" — record that verbatim. Do not silently skip.\n\nDo **NOT** proceed to Phase 3 until every required field has either an answer or an explicit \"not applicable\".\n\n### Phase 3: Code & related-context grounding\n\n**Goal:** Help maintainers find the relevant code fast.\n\nAsk the user for:\n- File paths or `file:line` references they suspect are involved (optional but encouraged).\n- Related issues / PRs to link (`Refs #N`, `Related to #N`).\n- Whether they tried searching existing issues (`gh issue list --search \"<keywords>\"`). If they have not and the report sounds like something that might exist, run the search and show top 3 matches before continuing.\n\nIf the user provides no code locations and the bug is concrete, optionally offer:\n> \"Want me to grep for the relevant code so we can include file:line in the issue?\"\n\nDo not grep silently — ask first, and only do it once.\n\n### Phase 4: Render, confirm, submit\n\n**Goal:** Show the final body, get explicit approval, file the issue.\n\n1. Read the chosen template:\n   ```\n   Read: .Codex/skills/issue-create/assets/<template>.md\n   ```\n2. Read the labels catalog:\n   ```\n   Read: .Codex/skills/issue-create/references/labels.md\n   ```\n3. Fill the template with the collected fields. Strip secrets per Important Rule #5.\n4. Pick labels:\n   - Always include the type label (Phase 1 mapping).\n   - Add `good first issue` only if the user explicitly says it qualifies (small scope, low context required).\n   - Add `help wanted` if the user has no plan to fix it themselves.\n   - Add `documentation` in addition to the type label if docs need updating.\n5. Show the user the complete rendered output:\n   ```\n   Title: <title>\n   Labels: <label1>, <label2>\n   Body:\n   <full body>\n   ```\n6. Ask: \"Ready to submit, or want to adjust anything?\"\n7. Wait for an explicit affirmative. \"Yes\", \"submit\", \"go\", \"looks good\", \"提交\" all qualify. Silence or hedging does not.\n8. Submit:\n   ```bash\n   gh issue create \\\n     --title \"<title>\" \\\n     --label \"<label1>,<label2>\" \\\n     --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n9. Print the issue URL.\n10. **STOP.** Do not assign, do not comment, do not link to projects unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not call `gh issue create` before showing the body for approval.\n- Do not invent reproduction steps when the user gave a vague report — ask.\n- Do not paste raw logs that contain tokens / cookies / OAuth state / account IDs.\n- Do not apply labels outside the existing catalog.\n- Do not file two issues from one report without confirming the split with the user.\n- Do not grep / search the codebase silently to \"fill in\" missing fields — ask first.\n",".agents/skills/issue-create/assets/bug-report.md":"<!--\nBug report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nMatch the language of the repo's existing issues (currently a mix of zh-CN and en).\n-->\n\n## Summary\n\n{{One sentence describing the bug.}}\n\n## Expected behavior\n\n{{What the user thought would happen.}}\n\n## Actual behavior\n\n{{What actually happened.}}\n\n## Reproduction steps\n\n1. {{step 1}}\n2. {{step 2}}\n3. {{step 3 — describe the failure}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| Frequency | {{always / intermittent / once}} |\n| First broken version (if known) | {{version or \"unknown\"}} |\n| Workaround (if any) | {{description or \"none\"}} |\n\n## Logs / output\n\n```\n{{Paste relevant log lines. SECRETS REDACTED — no tokens, cookies,\noauth_state, API keys, account IDs.}}\n```\n\n## Additional context\n\n{{Anything else the maintainer should know. Remove this section if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n",".agents/skills/issue-create/assets/feature-request.md":"<!--\nFeature request template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\n-->\n\n## Summary\n\n{{One sentence describing the feature.}}\n\n## Problem\n\n{{The user-facing motivation. What can the user not do today, or what is\npainful about how they have to do it? DO NOT describe the proposed\nsolution here — only the problem.}}\n\n## Proposed solution\n\n{{High-level description of how the feature would work. Implementation\ndetail is welcome but not required. If you have a UI in mind, sketch\nor screenshot helps.}}\n\n## Alternatives considered\n\n{{Other approaches the user thought about and why they don't fit.\nEven \"I considered X but it doesn't work because Y\" is useful — it\nsaves the maintainer from re-deriving the same conclusion.}}\n\n## Who benefits\n\n{{single user / all users / a specific deployment mode (Electron / Docker / dev) /\na specific upstream provider / a specific account state}}\n\n## Impact if not done\n\n{{Does the user have a workaround? Is this blocking? Nice-to-have?\nRemove this section if \"no impact, just nice\".}}\n\n## Additional context\n\n{{Mockups, links, related discussions. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n",".agents/skills/issue-create/assets/perf-report.md":"<!--\nPerformance report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nA perf report without numbers is just a bug — switch to bug-report.md if\nno measurements are available.\n-->\n\n## Summary\n\n{{One sentence describing the regression or slowness.}}\n\n## Expected behavior\n\n{{What performance was expected, and where that expectation comes from\n(prior version, docs, comparable system).}}\n\n## Actual behavior\n\n{{What is observed instead.}}\n\n## Measurements\n\n| Metric | Baseline | Current | Delta |\n|---|---|---|---|\n| {{e.g. p95 latency}} | {{200ms}} | {{1.4s}} | {{+600%}} |\n| {{e.g. memory RSS}} | {{180MB}} | {{420MB}} | {{+133%}} |\n\n**Methodology:** {{How the numbers were taken — script, manual stopwatch,\nprofiler, load test. Be specific enough that a maintainer can reproduce.}}\n\n## Reproduction harness\n\n```\n{{Script, `tests/bench/...` reference, or numbered steps. Must be\ndeterministic enough to re-measure.}}\n```\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| First slow version (if known) | {{version or \"unknown\"}} |\n| Resource constraint hit | {{CPU / memory / network / FDs / \"none\"}} |\n\n## Logs / output\n\n```\n{{Relevant log lines or profiler output. SECRETS REDACTED.}}\n```\n\n## Additional context\n\n{{Anything else. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n",".agents/skills/issue-create/assets/question.md":"<!--\nQuestion template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nNote: if it turns out to be a bug, switch to the bug-report template.\n-->\n\n## What I'm trying to accomplish\n\n{{The end goal, not the immediate confusion. e.g. \"I want to route\ngpt-5.5 traffic only to my work account\" — not \"what does\nplan_mapping do?\"}}\n\n## What I tried\n\n{{Commands, config snippets, docs read, search terms used. Be specific.}}\n\n```yaml\n# Relevant config — SECRETS REDACTED\n{{config snippet or \"none\"}}\n```\n\n## What I expected\n\n{{What outcome did you anticipate?}}\n\n## What happened\n\n{{What did you actually observe?}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n\n## Additional context\n\n{{Logs, screenshots, anything else. Remove if empty.}}\n",".agents/skills/issue-create/references/issue-types.md":"# Issue Type Specs\n\nRequired and optional fields per issue type. The skill enforces \"required\" — every required field must have either an answer or an explicit \"not applicable\" / \"unknown\" before the issue can be filed.\n\n## Bug\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Becomes part of the title; ≤72 chars |\n| Expected behavior | yes | What the user thought would happen |\n| Actual behavior | yes | What actually happened |\n| Reproduction steps | yes | Numbered list, deterministic |\n| Codex-proxy version | yes | `npm pkg get version` or About dialog |\n| Deployment mode | yes | Electron / Docker / `npm start` / dev / source |\n| OS + arch | yes | e.g. macOS 14.5 arm64, Windows 11 x64, Ubuntu 22.04 x64 |\n| Relevant logs | yes | Redact secrets; \"none\" is acceptable |\n| Frequency | yes | always / intermittent / once |\n| Workaround | no | If the user found one |\n| First broken version | no | If known (helps bisect) |\n| Related issues | no | `Refs #N` |\n\n## Feature Request\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Title material |\n| Problem statement | yes | The user-facing motivation. NOT the proposed solution. |\n| Proposed solution | yes | High level; implementation detail is welcome but optional |\n| Alternatives considered | yes | Even \"I considered X but it doesn't fit because Y\" |\n| Who benefits | yes | single user / all users / specific deployment mode / specific upstream |\n| Impact if NOT done | no | Does the user have a workaround? Is this blocking? |\n| Related issues / PRs | no | `Refs #N` |\n| Mockups / sketches | no | For UI features |\n\n## Question\n\n| Field | Required | Notes |\n|---|---|---|\n| What you're trying to accomplish | yes | The end goal, not the immediate confusion |\n| What you tried | yes | Commands, config, links to docs read |\n| What you expected | yes | |\n| What happened | yes | |\n| Relevant config | yes | Redact secrets; \"none\" if no config involved |\n| Codex-proxy version | yes | |\n| Deployment mode | yes | |\n\nIf a \"question\" turns out to be a bug during the interview, switch to the Bug template — do not file under `question`.\n\n## Performance\n\nAll Bug fields, plus:\n\n| Field | Required | Notes |\n|---|---|---|\n| Baseline measurement | yes | Numbers from a known-good version or expected baseline |\n| Current measurement | yes | Same metric, current version |\n| Measurement methodology | yes | How the numbers were taken — script, manual stopwatch, profiler |\n| Reproduction harness | yes | Script, `tests/bench/...` reference, or steps |\n| Resource constraint hit | no | CPU, memory, network, file descriptors, etc. |\n\nA perf report without numbers is a bug report — switch templates.\n\n## Documentation\n\n| Field | Required | Notes |\n|---|---|---|\n| Doc location | yes | File path (`README.md`, `CLAUDE.md`, `docs/...`) or URL |\n| What is wrong / missing | yes | Specific quote of the offending text, or \"this section is missing\" |\n| Suggested fix | no | Welcome but not required |\n| Audience affected | no | New users / operators / contributors / API consumers |\n",".agents/skills/issue-create/references/labels.md":"# Issue Labels (codex-proxy)\n\nThe complete catalog of labels currently defined on the repo. Apply only labels from this list — do not invent new ones. To propose a new label, file a `chore:` issue separately.\n\n| Label | Color | Use for |\n|---|---|---|\n| `bug` | #d73a4a | Something isn't working as documented or intended |\n| `enhancement` | #a2eeef | New feature or extension of an existing feature |\n| `documentation` | #0075ca | Improvements or additions to documentation |\n| `question` | #d876e3 | Further information is requested; not yet known to be a bug |\n| `help wanted` | #008672 | Maintainers welcome contributors to take this on |\n| `good first issue` | #7057ff | Small scope, low context required, friendly to newcomers |\n| `duplicate` | #cfd3d7 | Already filed elsewhere — set after triage, not on creation |\n| `invalid` | #e4e669 | Not actionable or out of scope — set after triage |\n| `wontfix` | #ffffff | Acknowledged but will not be addressed — set after triage |\n| `sync-conflict` | #d73a4a | `main → electron` auto-sync merge conflict — used by automation, not for human-filed issues |\n\n## Application rules for the skill\n\n1. **One type label minimum**: bug / enhancement / documentation / question (pick exactly one based on the issue type).\n2. **`good first issue`**: only when the user explicitly confirms the scope is small AND the fix is local (single file or single module).\n3. **`help wanted`**: when the reporter has no plan to send a PR themselves.\n4. **`documentation`** can be combined with `bug` or `enhancement` if the change requires both code and doc updates.\n5. **Never apply on creation**: `duplicate`, `invalid`, `wontfix`, `sync-conflict`. These are triage / automation labels.\n\n## CLI form\n\n```bash\ngh issue create --label \"bug,help wanted\" ...\n```\n\nMultiple labels are comma-separated (no space after the comma).\n",".agents/skills/pr-push/SKILL.md":"---\nname: pr-push\ndescription: >-\n  Package the current working changes into a standards-compliant codex-proxy pull request:\n  branch hygiene, commit message linting, CHANGELOG prompt, conventional commit, push, and `gh pr create` against the `dev` branch.\n  TRIGGER when: user asks to \"push a PR\", \"open a PR\", \"create PR\", \"ship this\", \"推 PR\", \"开 PR\", \"提交 PR\".\n  DO NOT TRIGGER when: user only wants to commit without pushing; user explicitly wants to push directly to main; user wants to merge, rebase, or close an existing PR (use `gh pr merge` / `gh pr close` directly).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Edit\"\n  - \"Write\"\n  - \"Grep\"\n---\n\n# PR Push\n\nTurn the current working tree into a clean PR targeting `dev`. This skill enforces codex-proxy's contribution rules so community maintainers do not have to memorize them.\n\n## Overview\n\nCodex-proxy uses a `dev` → `main` promotion flow with strict commit conventions, CHANGELOG discipline, and a pre-push validation hook. This skill walks the maintainer through an interview, makes the commit, runs the push (letting the hook gate quality), and opens the PR. It explicitly stops before merge — review and merge are separate human decisions.\n\n## When to Use\n\n- A maintainer has finished a unit of work in their working tree and wants it on `dev`.\n- A maintainer asks to \"open a PR\" or equivalent and the working tree has changes (staged, unstaged, or untracked).\n\n## Important Rules\n\n1. **Target branch is always `dev`.** Never open a PR against `main` unless the user explicitly states \"target main\" with a written reason. The `main` branch is fast-forwarded by the `promote-dev-to-main.yml` workflow — manual PRs to `main` break that contract.\n2. **Never commit on `dev` or `main` directly.** If `git branch --show-current` is one of these, stop and ask the user to name a feature branch (`git switch -c <name>`).\n3. **Never use `git add -A`, `git add .`, or `git add -f`.** Stage files by explicit path. `-f` overrides `.gitignore` and has been the cause of secret leaks elsewhere.\n4. **Never pass `--no-verify` to `git commit` or `git push`.** The hook is the gate. If it fails, fix the underlying issue, do not bypass.\n5. **Stop after `gh pr create`.** Do not merge, do not approve, do not enable auto-merge. Pushing a PR and merging a PR are two human decisions.\n6. **CHANGELOG gate.** If any file under `src/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` changed, `CHANGELOG.md`'s `[Unreleased]` section MUST have a new entry covering the change before the commit is created.\n7. **Commit message format is fixed:** `<type>(<optional-scope>): <imperative summary>`. The type set is enumerated in `references/commit-conventions.md`.\n\n## Key Workflows\n\n### Phase 1: Discovery (interview, do not touch the repo yet)\n\n**Goal:** Understand what is being shipped before any git operation.\n\nRun these read-only commands in parallel and summarize results back to the user:\n\n```\ngit branch --show-current\ngit status --short\ngit diff --stat\ngit log --oneline -10\n```\n\nThen read the conventions:\n```\nRead: .Codex/skills/pr-push/references/commit-conventions.md\nRead: .Codex/skills/pr-push/references/changelog-format.md\nRead: .Codex/skills/pr-push/references/pr-checklist.md\n```\n\nAsk the user (in one consolidated message) for any field that cannot be inferred:\n\n- **Commit type** (feat / fix / refactor / docs / test / chore / perf / ci) — propose one based on the diff, ask for confirmation.\n- **One-line summary** (imperative, lowercase, no trailing period) — propose one based on the diff.\n- **PR target** — default `dev`. Confirm only if the user previously asked to deviate.\n- **CHANGELOG entry** — if the gate in Important Rules #6 applies and `CHANGELOG.md` `[Unreleased]` has no matching entry, ask the user to dictate one (or offer to draft one for review). Do not invent silently.\n- **Memory / docs touch** — if the change touches public protocol, request flow, auth lifecycle, or release infra, ask whether `AGENTS.md` needs updating in the same PR.\n\nDo **NOT** proceed to Phase 2 until the user has explicitly confirmed (a) commit type, (b) summary, (c) CHANGELOG status, (d) target = `dev`.\n\n### Phase 2: Branch hygiene\n\n**Goal:** Make sure the commit lands on a feature branch, not on `dev`/`main`.\n\n1. Check `git branch --show-current`.\n2. If the current branch is `dev` or `main`:\n   - Stop. Ask the user to provide a feature branch name (suggest one derived from the commit summary, kebab-case, ≤40 chars).\n   - Run `git switch -c <name>`. Do not auto-pick a name without confirmation.\n3. If the current branch is a feature branch but is not based on up-to-date `origin/dev`:\n   - Run `git fetch origin dev`.\n   - If `git merge-base --is-ancestor origin/dev HEAD` is false (branch is behind), warn the user and ask whether to `git rebase origin/dev` before continuing. Do not rebase silently.\n\n### Phase 3: Stage + commit\n\n**Goal:** Produce one well-formed commit.\n\n1. List the files the user wants in this commit. If they didn't say, propose the list from `git status --short` and confirm.\n2. Run `git add <file1> <file2> ...` with explicit paths. Never `-A`, `.`, or `-f`.\n3. If CHANGELOG was updated as part of Phase 1, include `CHANGELOG.md` in the staged set.\n4. Build the commit message:\n   - First line: `<type>(<scope>): <summary>` — scope is optional, omit parentheses if no scope.\n   - Body (optional): wrap at ~72 cols, explain *why*, reference issues with `Closes #N` / `Refs #N` if applicable.\n5. Commit with a HEREDOC (preserves formatting):\n   ```bash\n   git commit -m \"$(cat <<'EOF'\n   <type>(<scope>): <summary>\n\n   <optional body>\n   EOF\n   )\"\n   ```\n6. If the commit fails because of a pre-commit hook, fix the reported issue and create a NEW commit (do not `--amend`). Re-run the same command after fixes.\n\n### Phase 4: Push\n\n**Goal:** Get the branch to `origin` so a PR can be opened.\n\n1. Confirm the user wants to push (a single short \"ready to push?\" — they may have wanted to inspect the commit first).\n2. **Hook presence check.** The repo's pre-push gate lives at `.Codex/hooks/pre-push-validate.sh`, which is gitignored — fresh clones do **not** have it. Run `test -x .Codex/hooks/pre-push-validate.sh`:\n   - **Hook present** → push normally; the hook will run.\n   - **Hook missing** → warn the user that no pre-push gate is installed, then run the equivalent checks inline based on what the diff touched, before pushing:\n     | Diff touches | Run |\n     |---|---|\n     | `src/**` or `tests/**` | `npm test` and `npx tsc --noEmit` |\n     | `web/**` | `npm run build` |\n     | `Dockerfile`, `docker-compose*` | `docker build .` (or note user must verify) |\n     | `packages/electron/**`, `electron-builder.yml` | `npm run -w packages/electron build` |\n     | `native/**` | `npm run -w native build` |\n     Any failure aborts the push — fix and re-run.\n3. Run `git push -u origin HEAD`.\n4. If the push is blocked by the hook:\n   - Read the hook output verbatim back to the user.\n   - The hook validates the build targets affected by the diff (test, tsc, web build, Dockerfile lint, Electron config, native addon). Identify which target failed and propose a fix.\n   - **Never retry with `--no-verify`.** Re-run the offending check locally, fix the root cause, amend the commit only if the user authorizes it, otherwise add a fix-up commit.\n\n### Phase 5: Open the PR\n\n**Goal:** Create a PR against `dev` with a body that future reviewers can read cold.\n\n1. Read the PR body template:\n   ```\n   Read: .Codex/skills/pr-push/assets/pr-body-template.md\n   ```\n2. Determine PR title:\n   - If the branch has a single commit, reuse the commit subject.\n   - If multiple commits, propose a title that summarizes the branch's intent and confirm with user.\n   - Title MUST start with a conventional type, MUST be ≤72 chars.\n3. Fill the body sections (Summary / Test Plan / Notes). Source content from:\n   - `git log <base>..HEAD` for the change list.\n   - The CHANGELOG entry the user wrote.\n   - Test commands actually run locally (do not invent test results).\n4. Show the rendered title + body to the user. **Wait for explicit \"looks good\" before invoking `gh`.**\n5. Create the PR:\n   ```bash\n   gh pr create --base dev --title \"<title>\" --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n6. Print the PR URL.\n7. **STOP.** Do not run `gh pr merge`, `gh pr review --approve`, `gh pr edit --add-label`, or `--auto-merge` unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not assume the user wants every modified file in the PR — ask.\n- Do not auto-write the CHANGELOG entry without showing it for approval first.\n- Do not retry a failing pre-push hook with `--no-verify`.\n- Do not open the PR against `main` even if the user is on a branch named `main-fix-X` — branch name does not imply target.\n- Do not silently rebase. If the branch needs rebase against `origin/dev`, ask first.\n- Do not chain `gh pr create` with `gh pr merge`. Two separate decisions.\n",".agents/skills/pr-push/assets/pr-body-template.md":"<!--\nPR body template for codex-proxy. The skill fills in the {{placeholders}}\nand removes optional sections that don't apply. Default language follows\nthe repo's dominant language (currently zh-CN for CHANGELOG entries,\nen for code/commits). Pick one and stay consistent within a single PR.\n-->\n\n## Summary\n\n{{One paragraph: WHAT changed and WHY. Reference the user-visible impact.\nIf multiple commits, summarize the branch's intent, not each commit.}}\n\n## Changes\n\n{{Bulleted list mirroring the CHANGELOG entry. Group by area when the PR\ntouches multiple modules. Reference file paths so reviewers can navigate.}}\n\n- {{change 1 — files}}\n- {{change 2 — files}}\n\n## Test Plan\n\n{{List the commands actually run locally. Do not invent results.\nMark checked items with [x], unchecked with [ ].}}\n\n- [ ] `npm test`\n- [ ] `npm run build`\n- [ ] {{any feature-specific manual verification, e.g. \"Verified Dashboard 用量页 cache hit card renders with mock data\"}}\n- [ ] {{`npm run test:real` if the change touches upstream protocol}}\n\n## Notes\n\n{{Optional. Use for any of:\n - Reviewer attention requests (\"please double-check the SSE buffer math in src/...\")\n - Known follow-ups (\"memory entry for new RT format will land in a separate PR\")\n - Migration / config impact (\"operators must add `update.allow_prerelease` if they want beta\")\n - Screenshots for UI changes\nRemove this section if there are no notes.}}\n\n## Linked Issues\n\n{{Closes #N / Refs #N — remove if none.}}\n",".agents/skills/pr-push/references/changelog-format.md":"# CHANGELOG Format\n\nCodex-proxy follows [Keep a Changelog](https://keepachangelog.com/). Every PR that changes user-visible behavior, public API, configuration, or build/release infrastructure MUST add an entry to `CHANGELOG.md` under `## [Unreleased]`.\n\n## Section Layout\n\n`## [Unreleased]` contains exactly these subsections (in this order, omit empty ones):\n\n```markdown\n## [Unreleased]\n\n### Changed\n\n- ...\n\n### Added\n\n- ...\n\n### Fixed\n\n- ...\n```\n\n| Subsection | Use for |\n|---|---|\n| `### Added` | New features, new endpoints, new config keys, new CLI flags |\n| `### Changed` | Behavior change of existing features, default value changes, signature changes |\n| `### Fixed` | Bug fixes |\n| `### Removed` | Deleted features (rare; gate behind a deprecation cycle first) |\n| `### Deprecated` | Marking something for future removal |\n| `### Security` | Security-relevant fix (CVE, cred leak, etc.) |\n\n## Entry Style\n\n- Use the same language as the existing `[Unreleased]` entries (zh-CN at time of writing). If the file flips to English, follow.\n- Lead with the user-visible impact, then mention the file paths in parentheses for reviewer navigation.\n- Reference issues / PRs with `(#NNN)` inline.\n- Multi-aspect entries get nested bullets.\n\n## Examples (from current `[Unreleased]`)\n\n```markdown\n### Added\n\n- 图像生成请求计数（成功 / 失败分流）：`AccountUsage` 新增 `image_request_count` / `image_request_failed_count`...\n- Dashboard 用量统计新增「缓存命中率」卡片...\n```\n\n```markdown\n### Changed\n\n- `bump-electron-beta.yml` 触发改为定时 cron（每天 04:00 / 12:00 UTC）...\n```\n\n## When NOT to add a CHANGELOG entry\n\nSkip CHANGELOG for commits that are:\n\n- Test-only (`test:` prefix) — no user impact\n- Doc-only edits to internal docs (`CLAUDE.md`, `.claude/`, `docs/dev-notes/`)\n- Pure refactors that change zero observed behavior (`refactor:` prefix with no API surface change)\n- CI-only changes that do not affect built artifacts (`ci:` prefix)\n- Style/formatting (`style:` prefix)\n\nIf unsure, **add the entry**. A redundant entry is cheaper than a missing one.\n\n## Multi-line / multi-bullet entries\n\nUse the existing nested bullet pattern:\n\n```markdown\n- Ollama bridge cleanup (#403 review followups, closes #405 #406 #407):\n  - `src/ollama/bridge.ts` 不再重复实现 `normalizeHostname`...\n  - `proxyOpenAIRequest` 转发头扩展到...\n  - `MAX_SSE_BUFFER` 重命名为 `MAX_SSE_BUFFER_CHARS`...\n```\n",".agents/skills/pr-push/references/commit-conventions.md":"# Commit Message Conventions\n\nCodex-proxy uses Conventional Commits with a fixed type vocabulary. Several CI workflows pattern-match on the type prefix, so unknown types break automation.\n\n## Format\n\n```\n<type>(<optional scope>): <imperative summary>\n\n<optional body — wrap at ~72 cols, explain WHY>\n\n<optional footer — Closes #N, Refs #N, BREAKING CHANGE: ...>\n```\n\n- Subject is **imperative mood**, lowercase first letter, no trailing period.\n- Subject ≤ 72 chars hard cap.\n- Body explains *why* the change was made, not *what* (the diff shows what).\n\n## Type Vocabulary\n\n| Type | Use for | Triggers beta release? |\n|---|---|---|\n| `feat` | New user-visible feature | yes |\n| `fix` | Bug fix | yes |\n| `perf` | Performance improvement with no behavior change | yes |\n| `refactor` | Code restructuring with no behavior change | no |\n| `docs` | Documentation only | no |\n| `test` | Test-only changes | no |\n| `chore` | Tooling, dependencies, repo housekeeping | no |\n| `ci` | CI/CD configuration | no |\n| `style` | Formatting, whitespace, no logic change | no |\n\nThe \"Triggers beta release?\" column is determined by `bump-electron-beta.yml`'s skip filter: `^(chore|docs|ci|test|refactor|style)`. Note that `fix(ci):` still triggers a beta release because the prefix is `fix`.\n\n## Scope\n\nOptional, but encouraged for clarity. Use the top-level module name:\n\n- `feat(auth): ...`\n- `fix(translation): ...`\n- `refactor(routes): ...`\n- `chore(deps): ...`\n- `ci(release): ...`\n\nSkip the scope when the change spans multiple modules or is genuinely repo-wide.\n\n## Examples\n\nGood:\n\n```\nfeat(auth): persist account-pool RT-only imports across restarts\n```\n\n```\nfix(translation): recover from previous_response_not_found instead of passing it through\n```\n\n```\nrefactor(routes): extract shared proxy-handler from openai/anthropic/gemini handlers\n```\n\nBad — and why:\n\n| Message | Why it fails |\n|---|---|\n| `Update auth.ts` | No type, describes WHAT not WHY |\n| `feat: Added new feature.` | Past tense + capitalized + trailing period |\n| `feature(auth): persist RT` | `feature` is not in the vocabulary, use `feat` |\n| `fix: stuff` | Subject is meaningless |\n| `wip` | No type, no information |\n\n## Multi-line body\n\nUse a HEREDOC to preserve formatting:\n\n```bash\ngit commit -m \"$(cat <<'EOF'\nfix(quota): ignore stale x-codex-* headers after token refresh\n\nThe previous behavior overwrote fresh quota state with cached headers\nfrom the old token, causing accounts to appear over-quota for ~30s\nafter refresh. Now we drop quota updates whose token id does not match\nthe current session.\n\nCloses #418\nEOF\n)\"\n```\n",".agents/skills/pr-push/references/pr-checklist.md":"# Pre-PR Self-Check\n\nWalk this list before opening the PR. Anything left unchecked needs a written reason in the PR body.\n\n## Branch & target\n\n- [ ] Current branch is NOT `dev` or `main`\n- [ ] Branch is rebased on (or fast-forwardable to) `origin/dev`\n- [ ] PR target = `dev`\n\n## Commit hygiene\n\n- [ ] Each commit follows `<type>(<scope>): <summary>` with a vocabulary type (see `commit-conventions.md`)\n- [ ] No commit was created with `--no-verify`\n- [ ] No file added with `git add -f`\n- [ ] No accidental staging of `node_modules/`, `dist/`, `*.log`, `.env*`, `data/`, or other gitignored paths\n- [ ] No secrets in code or commit messages (API keys, tokens, cookies, oauth_state)\n\n## CHANGELOG\n\n- [ ] If the change touches `src/`, `shared/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` → `CHANGELOG.md` `[Unreleased]` has a new entry\n- [ ] Entry placed in correct subsection (Added / Changed / Fixed)\n- [ ] Entry references the issue / PR number when applicable\n\n## Cross-artifact impact\n\nCodex-proxy ships three artifacts: backend (Docker), Electron desktop, web frontend. The pre-push hook will catch most of these, but verify mentally first:\n\n- [ ] If `src/` changed → backend logic still passes `npm test`\n- [ ] If `web/` changed → `npm run build` produces a clean Vite bundle\n- [ ] If `Dockerfile` / `docker-compose*` changed → image still builds\n- [ ] If `packages/electron/**` or `electron-builder.yml` changed → Electron config validates\n- [ ] If `native/**` changed → native addon still builds\n\n## Tests\n\n- [ ] New behavior has new tests (TDD: tests written first when feasible)\n- [ ] All affected `npm test` suites pass locally\n- [ ] No `*.skip` left behind unless explicitly justified in the PR body\n\n## TypeScript\n\n- [ ] No `any`, `as any`, `: any`, or `<any>` in new code (use `unknown`, generics, or specific types)\n- [ ] No `@ts-ignore` / `@ts-expect-error` without an inline explanation comment\n\n## Real-upstream changes\n\n- [ ] If the change touches the upstream protocol (translation/, proxy/, auth/), `npm run test:real` was attempted at least once\n\n## Documentation\n\n- [ ] Public-facing config/flag changes are reflected in `config/default.yaml` comments and `CLAUDE.md` if relevant\n- [ ] No internal personal notes leaked into committed files\n\n## After push (do NOT do these in this skill)\n\n- [ ] Wait for CI green before requesting review\n- [ ] Merge is a separate, explicit decision — never auto-merge from this skill\n",".claude/skills/issue-create/SKILL.md":"---\nname: issue-create\ndescription: >-\n  Interview the user to gather all required context, then open a high-quality GitHub issue (`gh issue create`) on the codex-proxy repo with the right template, labels, and structured body.\n  TRIGGER when: user says \"open an issue\", \"file an issue\", \"create issue\", \"report a bug\", \"feature request\", \"提个 issue\", \"报 bug\", \"提需求\".\n  DO NOT TRIGGER when: user wants to view, search, comment on, or close existing issues (use `gh issue list/view/comment/close` directly); user is writing a PR description (use `pr-push`).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Write\"\n---\n\n# Issue Create\n\nGather complete context through a structured interview, then file a well-formed issue. The interview is a hard gate — vague issues waste maintainer time.\n\n## Overview\n\nMost \"I have a bug\" or \"I want a feature\" reports are missing the information a maintainer needs to act. This skill runs a four-phase interview, fills the appropriate template, applies the right labels, and only then calls `gh issue create`. The user sees and approves the rendered body before submission.\n\n## When to Use\n\n- A user wants to file a new issue on the codex-proxy repository.\n- A user describes a bug or feature in conversation and asks \"should we file an issue?\"\n\n## Important Rules\n\n1. **The interview is not optional.** Do NOT call `gh issue create` until all required fields for the chosen type are collected and the user has explicitly approved the rendered body.\n2. **Never invent reproduction steps, version numbers, log output, or behavior.** If the user did not provide it, ask. If they cannot provide it, write \"not provided\" in the field, do not fabricate.\n3. **Show the full body before submitting.** The user must explicitly say \"submit\" / \"looks good\" / equivalent. \"Yes\" without seeing the body is not enough — show it first.\n4. **Apply only labels from the project's existing label set.** Read `references/labels.md` for the catalog. Do not invent new labels.\n5. **Strip secrets.** If the user pastes logs, headers, or config that contain tokens, cookies, OAuth state, API keys, or account IDs, redact them before they enter the issue body. Replace with `<redacted>`.\n6. **One issue per scope.** If the user describes two unrelated problems, file two issues. Ask before splitting.\n\n## Key Workflows\n\n### Phase 1: Type classification\n\n**Goal:** Pick the right template and label.\n\nAsk the user (one consolidated question):\n\n> What type of issue is this?\n>   1. **Bug** — something is broken or behaves incorrectly\n>   2. **Feature request** — propose new functionality\n>   3. **Question** — usage / configuration / \"is this expected?\"\n>   4. **Performance** — measurable regression or slowness\n>   5. **Documentation** — docs are wrong, missing, or unclear\n\nRead the type spec:\n```\nRead: .claude/skills/issue-create/references/issue-types.md\n```\n\nMap answer to template path:\n\n| Type | Template asset | Default label |\n|---|---|---|\n| Bug | `assets/bug-report.md` | `bug` |\n| Feature request | `assets/feature-request.md` | `enhancement` |\n| Question | `assets/question.md` | `question` |\n| Performance | `assets/perf-report.md` | `bug` |\n| Documentation | `assets/feature-request.md` (with docs framing) | `documentation` |\n\nDo **NOT** proceed to Phase 2 until the type is confirmed.\n\n### Phase 2: Required-field interview\n\n**Goal:** Collect every field the chosen template requires.\n\nRead `references/issue-types.md` to see the required-field table for the chosen type. Ask for missing fields in **one consolidated message**, not one at a time. Group related fields together.\n\n**For bugs**, the required fields are:\n- One-line summary\n- Expected behavior\n- Actual behavior\n- Reproduction steps (numbered)\n- Codex-proxy version (`npm pkg get version` or app About dialog)\n- Deployment mode (Electron app / Docker / `npm start` / dev)\n- Relevant log lines (redact secrets)\n- Frequency (always / intermittent / once)\n\n**For feature requests**, the required fields are:\n- Problem the feature solves (user-facing motivation, not the proposed solution)\n- Proposed solution (high level)\n- Alternatives considered\n- Who benefits (single user / all users / specific deployment mode)\n\n**For questions**:\n- What you tried\n- What you expected\n- What happened\n- Relevant config (redact secrets)\n\n**For performance**:\n- All bug fields, plus:\n- Measured baseline vs current (timings, memory, request count — be specific)\n- Reproduction harness (script, steps, or `tests/bench/`)\n\n**For documentation**:\n- Which doc page / file\n- What is wrong or missing\n- Suggested fix (if any)\n\nIf a field cannot be answered, the user must explicitly say \"not applicable\" or \"unknown\" — record that verbatim. Do not silently skip.\n\nDo **NOT** proceed to Phase 3 until every required field has either an answer or an explicit \"not applicable\".\n\n### Phase 3: Code & related-context grounding\n\n**Goal:** Help maintainers find the relevant code fast.\n\nAsk the user for:\n- File paths or `file:line` references they suspect are involved (optional but encouraged).\n- Related issues / PRs to link (`Refs #N`, `Related to #N`).\n- Whether they tried searching existing issues (`gh issue list --search \"<keywords>\"`). If they have not and the report sounds like something that might exist, run the search and show top 3 matches before continuing.\n\nIf the user provides no code locations and the bug is concrete, optionally offer:\n> \"Want me to grep for the relevant code so we can include file:line in the issue?\"\n\nDo not grep silently — ask first, and only do it once.\n\n### Phase 4: Render, confirm, submit\n\n**Goal:** Show the final body, get explicit approval, file the issue.\n\n1. Read the chosen template:\n   ```\n   Read: .claude/skills/issue-create/assets/<template>.md\n   ```\n2. Read the labels catalog:\n   ```\n   Read: .claude/skills/issue-create/references/labels.md\n   ```\n3. Fill the template with the collected fields. Strip secrets per Important Rule #5.\n4. Pick labels:\n   - Always include the type label (Phase 1 mapping).\n   - Add `good first issue` only if the user explicitly says it qualifies (small scope, low context required).\n   - Add `help wanted` if the user has no plan to fix it themselves.\n   - Add `documentation` in addition to the type label if docs need updating.\n5. Show the user the complete rendered output:\n   ```\n   Title: <title>\n   Labels: <label1>, <label2>\n   Body:\n   <full body>\n   ```\n6. Ask: \"Ready to submit, or want to adjust anything?\"\n7. Wait for an explicit affirmative. \"Yes\", \"submit\", \"go\", \"looks good\", \"提交\" all qualify. Silence or hedging does not.\n8. Submit:\n   ```bash\n   gh issue create \\\n     --title \"<title>\" \\\n     --label \"<label1>,<label2>\" \\\n     --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n9. Print the issue URL.\n10. **STOP.** Do not assign, do not comment, do not link to projects unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not call `gh issue create` before showing the body for approval.\n- Do not invent reproduction steps when the user gave a vague report — ask.\n- Do not paste raw logs that contain tokens / cookies / OAuth state / account IDs.\n- Do not apply labels outside the existing catalog.\n- Do not file two issues from one report without confirming the split with the user.\n- Do not grep / search the codebase silently to \"fill in\" missing fields — ask first.\n",".claude/skills/issue-create/assets/bug-report.md":"<!--\nBug report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nMatch the language of the repo's existing issues (currently a mix of zh-CN and en).\n-->\n\n## Summary\n\n{{One sentence describing the bug.}}\n\n## Expected behavior\n\n{{What the user thought would happen.}}\n\n## Actual behavior\n\n{{What actually happened.}}\n\n## Reproduction steps\n\n1. {{step 1}}\n2. {{step 2}}\n3. {{step 3 — describe the failure}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| Frequency | {{always / intermittent / once}} |\n| First broken version (if known) | {{version or \"unknown\"}} |\n| Workaround (if any) | {{description or \"none\"}} |\n\n## Logs / output\n\n```\n{{Paste relevant log lines. SECRETS REDACTED — no tokens, cookies,\noauth_state, API keys, account IDs.}}\n```\n\n## Additional context\n\n{{Anything else the maintainer should know. Remove this section if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n",".claude/skills/issue-create/assets/feature-request.md":"<!--\nFeature request template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\n-->\n\n## Summary\n\n{{One sentence describing the feature.}}\n\n## Problem\n\n{{The user-facing motivation. What can the user not do today, or what is\npainful about how they have to do it? DO NOT describe the proposed\nsolution here — only the problem.}}\n\n## Proposed solution\n\n{{High-level description of how the feature would work. Implementation\ndetail is welcome but not required. If you have a UI in mind, sketch\nor screenshot helps.}}\n\n## Alternatives considered\n\n{{Other approaches the user thought about and why they don't fit.\nEven \"I considered X but it doesn't work because Y\" is useful — it\nsaves the maintainer from re-deriving the same conclusion.}}\n\n## Who benefits\n\n{{single user / all users / a specific deployment mode (Electron / Docker / dev) /\na specific upstream provider / a specific account state}}\n\n## Impact if not done\n\n{{Does the user have a workaround? Is this blocking? Nice-to-have?\nRemove this section if \"no impact, just nice\".}}\n\n## Additional context\n\n{{Mockups, links, related discussions. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n",".claude/skills/issue-create/assets/perf-report.md":"<!--\nPerformance report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nA perf report without numbers is just a bug — switch to bug-report.md if\nno measurements are available.\n-->\n\n## Summary\n\n{{One sentence describing the regression or slowness.}}\n\n## Expected behavior\n\n{{What performance was expected, and where that expectation comes from\n(prior version, docs, comparable system).}}\n\n## Actual behavior\n\n{{What is observed instead.}}\n\n## Measurements\n\n| Metric | Baseline | Current | Delta |\n|---|---|---|---|\n| {{e.g. p95 latency}} | {{200ms}} | {{1.4s}} | {{+600%}} |\n| {{e.g. memory RSS}} | {{180MB}} | {{420MB}} | {{+133%}} |\n\n**Methodology:** {{How the numbers were taken — script, manual stopwatch,\nprofiler, load test. Be specific enough that a maintainer can reproduce.}}\n\n## Reproduction harness\n\n```\n{{Script, `tests/bench/...` reference, or numbered steps. Must be\ndeterministic enough to re-measure.}}\n```\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| First slow version (if known) | {{version or \"unknown\"}} |\n| Resource constraint hit | {{CPU / memory / network / FDs / \"none\"}} |\n\n## Logs / output\n\n```\n{{Relevant log lines or profiler output. SECRETS REDACTED.}}\n```\n\n## Additional context\n\n{{Anything else. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n",".claude/skills/issue-create/assets/question.md":"<!--\nQuestion template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nNote: if it turns out to be a bug, switch to the bug-report template.\n-->\n\n## What I'm trying to accomplish\n\n{{The end goal, not the immediate confusion. e.g. \"I want to route\ngpt-5.5 traffic only to my work account\" — not \"what does\nplan_mapping do?\"}}\n\n## What I tried\n\n{{Commands, config snippets, docs read, search terms used. Be specific.}}\n\n```yaml\n# Relevant config — SECRETS REDACTED\n{{config snippet or \"none\"}}\n```\n\n## What I expected\n\n{{What outcome did you anticipate?}}\n\n## What happened\n\n{{What did you actually observe?}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n\n## Additional context\n\n{{Logs, screenshots, anything else. Remove if empty.}}\n",".claude/skills/issue-create/references/issue-types.md":"# Issue Type Specs\n\nRequired and optional fields per issue type. The skill enforces \"required\" — every required field must have either an answer or an explicit \"not applicable\" / \"unknown\" before the issue can be filed.\n\n## Bug\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Becomes part of the title; ≤72 chars |\n| Expected behavior | yes | What the user thought would happen |\n| Actual behavior | yes | What actually happened |\n| Reproduction steps | yes | Numbered list, deterministic |\n| Codex-proxy version | yes | `npm pkg get version` or About dialog |\n| Deployment mode | yes | Electron / Docker / `npm start` / dev / source |\n| OS + arch | yes | e.g. macOS 14.5 arm64, Windows 11 x64, Ubuntu 22.04 x64 |\n| Relevant logs | yes | Redact secrets; \"none\" is acceptable |\n| Frequency | yes | always / intermittent / once |\n| Workaround | no | If the user found one |\n| First broken version | no | If known (helps bisect) |\n| Related issues | no | `Refs #N` |\n\n## Feature Request\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Title material |\n| Problem statement | yes | The user-facing motivation. NOT the proposed solution. |\n| Proposed solution | yes | High level; implementation detail is welcome but optional |\n| Alternatives considered | yes | Even \"I considered X but it doesn't fit because Y\" |\n| Who benefits | yes | single user / all users / specific deployment mode / specific upstream |\n| Impact if NOT done | no | Does the user have a workaround? Is this blocking? |\n| Related issues / PRs | no | `Refs #N` |\n| Mockups / sketches | no | For UI features |\n\n## Question\n\n| Field | Required | Notes |\n|---|---|---|\n| What you're trying to accomplish | yes | The end goal, not the immediate confusion |\n| What you tried | yes | Commands, config, links to docs read |\n| What you expected | yes | |\n| What happened | yes | |\n| Relevant config | yes | Redact secrets; \"none\" if no config involved |\n| Codex-proxy version | yes | |\n| Deployment mode | yes | |\n\nIf a \"question\" turns out to be a bug during the interview, switch to the Bug template — do not file under `question`.\n\n## Performance\n\nAll Bug fields, plus:\n\n| Field | Required | Notes |\n|---|---|---|\n| Baseline measurement | yes | Numbers from a known-good version or expected baseline |\n| Current measurement | yes | Same metric, current version |\n| Measurement methodology | yes | How the numbers were taken — script, manual stopwatch, profiler |\n| Reproduction harness | yes | Script, `tests/bench/...` reference, or steps |\n| Resource constraint hit | no | CPU, memory, network, file descriptors, etc. |\n\nA perf report without numbers is a bug report — switch templates.\n\n## Documentation\n\n| Field | Required | Notes |\n|---|---|---|\n| Doc location | yes | File path (`README.md`, `CLAUDE.md`, `docs/...`) or URL |\n| What is wrong / missing | yes | Specific quote of the offending text, or \"this section is missing\" |\n| Suggested fix | no | Welcome but not required |\n| Audience affected | no | New users / operators / contributors / API consumers |\n",".claude/skills/issue-create/references/labels.md":"# Issue Labels (codex-proxy)\n\nThe complete catalog of labels currently defined on the repo. Apply only labels from this list — do not invent new ones. To propose a new label, file a `chore:` issue separately.\n\n| Label | Color | Use for |\n|---|---|---|\n| `bug` | #d73a4a | Something isn't working as documented or intended |\n| `enhancement` | #a2eeef | New feature or extension of an existing feature |\n| `documentation` | #0075ca | Improvements or additions to documentation |\n| `question` | #d876e3 | Further information is requested; not yet known to be a bug |\n| `help wanted` | #008672 | Maintainers welcome contributors to take this on |\n| `good first issue` | #7057ff | Small scope, low context required, friendly to newcomers |\n| `duplicate` | #cfd3d7 | Already filed elsewhere — set after triage, not on creation |\n| `invalid` | #e4e669 | Not actionable or out of scope — set after triage |\n| `wontfix` | #ffffff | Acknowledged but will not be addressed — set after triage |\n| `sync-conflict` | #d73a4a | `master → electron` auto-sync merge conflict — used by automation, not for human-filed issues |\n\n## Application rules for the skill\n\n1. **One type label minimum**: bug / enhancement / documentation / question (pick exactly one based on the issue type).\n2. **`good first issue`**: only when the user explicitly confirms the scope is small AND the fix is local (single file or single module).\n3. **`help wanted`**: when the reporter has no plan to send a PR themselves.\n4. **`documentation`** can be combined with `bug` or `enhancement` if the change requires both code and doc updates.\n5. **Never apply on creation**: `duplicate`, `invalid`, `wontfix`, `sync-conflict`. These are triage / automation labels.\n\n## CLI form\n\n```bash\ngh issue create --label \"bug,help wanted\" ...\n```\n\nMultiple labels are comma-separated (no space after the comma).\n",".claude/skills/pr-push/SKILL.md":"---\nname: pr-push\ndescription: >-\n  Package the current working changes into a standards-compliant codex-proxy pull request:\n  branch hygiene, commit message linting, CHANGELOG prompt, conventional commit, push, and `gh pr create` against the `dev` branch.\n  TRIGGER when: user asks to \"push a PR\", \"open a PR\", \"create PR\", \"ship this\", \"推 PR\", \"开 PR\", \"提交 PR\".\n  DO NOT TRIGGER when: user only wants to commit without pushing; user explicitly wants to push directly to master/main; user wants to merge, rebase, or close an existing PR (use `gh pr merge` / `gh pr close` directly).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Edit\"\n  - \"Write\"\n  - \"Grep\"\n---\n\n# PR Push\n\nTurn the current working tree into a clean PR targeting `dev`. This skill enforces codex-proxy's contribution rules so community maintainers do not have to memorize them.\n\n## Overview\n\nCodex-proxy uses a `dev` → `master` promotion flow with strict commit conventions, CHANGELOG discipline, and a pre-push validation hook. This skill walks the maintainer through an interview, makes the commit, runs the push (letting the hook gate quality), and opens the PR. It explicitly stops before merge — review and merge are separate human decisions.\n\n## When to Use\n\n- A maintainer has finished a unit of work in their working tree and wants it on `dev`.\n- A maintainer asks to \"open a PR\" or equivalent and the working tree has changes (staged, unstaged, or untracked).\n\n## Important Rules\n\n1. **Target branch is always `dev`.** Never open a PR against `master` or `main` unless the user explicitly states \"target master\" with a written reason. The `master` branch is fast-forwarded by the `promote-dev-to-master.yml` workflow — manual PRs to `master` break that contract.\n2. **Never commit on `dev`, `master`, or `main` directly.** If `git branch --show-current` is one of these, stop and ask the user to name a feature branch (`git switch -c <name>`).\n3. **Never use `git add -A`, `git add .`, or `git add -f`.** Stage files by explicit path. `-f` overrides `.gitignore` and has been the cause of secret leaks elsewhere.\n4. **Never pass `--no-verify` to `git commit` or `git push`.** The hook is the gate. If it fails, fix the underlying issue, do not bypass.\n5. **Stop after `gh pr create`.** Do not merge, do not approve, do not enable auto-merge. Pushing a PR and merging a PR are two human decisions.\n6. **CHANGELOG gate.** If any file under `src/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` changed, `CHANGELOG.md`'s `[Unreleased]` section MUST have a new entry covering the change before the commit is created.\n7. **Commit message format is fixed:** `<type>(<optional-scope>): <imperative summary>`. The type set is enumerated in `references/commit-conventions.md`.\n\n## Key Workflows\n\n### Phase 1: Discovery (interview, do not touch the repo yet)\n\n**Goal:** Understand what is being shipped before any git operation.\n\nRun these read-only commands in parallel and summarize results back to the user:\n\n```\ngit branch --show-current\ngit status --short\ngit diff --stat\ngit log --oneline -10\n```\n\nThen read the conventions:\n```\nRead: .claude/skills/pr-push/references/commit-conventions.md\nRead: .claude/skills/pr-push/references/changelog-format.md\nRead: .claude/skills/pr-push/references/pr-checklist.md\n```\n\nAsk the user (in one consolidated message) for any field that cannot be inferred:\n\n- **Commit type** (feat / fix / refactor / docs / test / chore / perf / ci) — propose one based on the diff, ask for confirmation.\n- **One-line summary** (imperative, lowercase, no trailing period) — propose one based on the diff.\n- **PR target** — default `dev`. Confirm only if the user previously asked to deviate.\n- **CHANGELOG entry** — if the gate in Important Rules #6 applies and `CHANGELOG.md` `[Unreleased]` has no matching entry, ask the user to dictate one (or offer to draft one for review). Do not invent silently.\n- **Memory / docs touch** — if the change touches public protocol, request flow, auth lifecycle, or release infra, ask whether `CLAUDE.md` needs updating in the same PR.\n\nDo **NOT** proceed to Phase 2 until the user has explicitly confirmed (a) commit type, (b) summary, (c) CHANGELOG status, (d) target = `dev`.\n\n### Phase 2: Branch hygiene\n\n**Goal:** Make sure the commit lands on a feature branch, not on `dev`/`master`.\n\n1. Check `git branch --show-current`.\n2. If the current branch is `dev`, `master`, or `main`:\n   - Stop. Ask the user to provide a feature branch name (suggest one derived from the commit summary, kebab-case, ≤40 chars).\n   - Run `git switch -c <name>`. Do not auto-pick a name without confirmation.\n3. If the current branch is a feature branch but is not based on up-to-date `origin/dev`:\n   - Run `git fetch origin dev`.\n   - If `git merge-base --is-ancestor origin/dev HEAD` is false (branch is behind), warn the user and ask whether to `git rebase origin/dev` before continuing. Do not rebase silently.\n\n### Phase 3: Stage + commit\n\n**Goal:** Produce one well-formed commit.\n\n1. List the files the user wants in this commit. If they didn't say, propose the list from `git status --short` and confirm.\n2. Run `git add <file1> <file2> ...` with explicit paths. Never `-A`, `.`, or `-f`.\n3. If CHANGELOG was updated as part of Phase 1, include `CHANGELOG.md` in the staged set.\n4. Build the commit message:\n   - First line: `<type>(<scope>): <summary>` — scope is optional, omit parentheses if no scope.\n   - Body (optional): wrap at ~72 cols, explain *why*, reference issues with `Closes #N` / `Refs #N` if applicable.\n5. Commit with a HEREDOC (preserves formatting):\n   ```bash\n   git commit -m \"$(cat <<'EOF'\n   <type>(<scope>): <summary>\n\n   <optional body>\n   EOF\n   )\"\n   ```\n6. If the commit fails because of a pre-commit hook, fix the reported issue and create a NEW commit (do not `--amend`). Re-run the same command after fixes.\n\n### Phase 4: Push\n\n**Goal:** Get the branch to `origin` so a PR can be opened.\n\n1. Confirm the user wants to push (a single short \"ready to push?\" — they may have wanted to inspect the commit first).\n2. **Hook presence check.** The repo's pre-push gate lives at `.claude/hooks/pre-push-validate.sh`, which is gitignored — fresh clones do **not** have it. Run `test -x .claude/hooks/pre-push-validate.sh`:\n   - **Hook present** → push normally; the hook will run.\n   - **Hook missing** → warn the user that no pre-push gate is installed, then run the equivalent checks inline based on what the diff touched, before pushing:\n     | Diff touches | Run |\n     |---|---|\n     | `src/**` or `tests/**` | `npm test` and `npx tsc --noEmit` |\n     | `web/**` | `npm run build` |\n     | `Dockerfile`, `docker-compose*` | `docker build .` (or note user must verify) |\n     | `packages/electron/**`, `electron-builder.yml` | `npm run -w packages/electron build` |\n     | `native/**` | `npm run -w native build` |\n     Any failure aborts the push — fix and re-run.\n3. Run `git push -u origin HEAD`.\n4. If the push is blocked by the hook:\n   - Read the hook output verbatim back to the user.\n   - The hook validates the build targets affected by the diff (test, tsc, web build, Dockerfile lint, Electron config, native addon). Identify which target failed and propose a fix.\n   - **Never retry with `--no-verify`.** Re-run the offending check locally, fix the root cause, amend the commit only if the user authorizes it, otherwise add a fix-up commit.\n\n### Phase 5: Open the PR\n\n**Goal:** Create a PR against `dev` with a body that future reviewers can read cold.\n\n1. Read the PR body template:\n   ```\n   Read: .claude/skills/pr-push/assets/pr-body-template.md\n   ```\n2. Determine PR title:\n   - If the branch has a single commit, reuse the commit subject.\n   - If multiple commits, propose a title that summarizes the branch's intent and confirm with user.\n   - Title MUST start with a conventional type, MUST be ≤72 chars.\n3. Fill the body sections (Summary / Test Plan / Notes). Source content from:\n   - `git log <base>..HEAD` for the change list.\n   - The CHANGELOG entry the user wrote.\n   - Test commands actually run locally (do not invent test results).\n4. Show the rendered title + body to the user. **Wait for explicit \"looks good\" before invoking `gh`.**\n5. Create the PR:\n   ```bash\n   gh pr create --base dev --title \"<title>\" --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n6. Print the PR URL.\n7. **STOP.** Do not run `gh pr merge`, `gh pr review --approve`, `gh pr edit --add-label`, or `--auto-merge` unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not assume the user wants every modified file in the PR — ask.\n- Do not auto-write the CHANGELOG entry without showing it for approval first.\n- Do not retry a failing pre-push hook with `--no-verify`.\n- Do not open the PR against `master` even if the user is on a branch named `master-fix-X` — branch name does not imply target.\n- Do not silently rebase. If the branch needs rebase against `origin/dev`, ask first.\n- Do not chain `gh pr create` with `gh pr merge`. Two separate decisions.\n",".claude/skills/pr-push/assets/pr-body-template.md":"<!--\nPR body template for codex-proxy. The skill fills in the {{placeholders}}\nand removes optional sections that don't apply. Default language follows\nthe repo's dominant language (currently zh-CN for CHANGELOG entries,\nen for code/commits). Pick one and stay consistent within a single PR.\n-->\n\n## Summary\n\n{{One paragraph: WHAT changed and WHY. Reference the user-visible impact.\nIf multiple commits, summarize the branch's intent, not each commit.}}\n\n## Changes\n\n{{Bulleted list mirroring the CHANGELOG entry. Group by area when the PR\ntouches multiple modules. Reference file paths so reviewers can navigate.}}\n\n- {{change 1 — files}}\n- {{change 2 — files}}\n\n## Test Plan\n\n{{List the commands actually run locally. Do not invent results.\nMark checked items with [x], unchecked with [ ].}}\n\n- [ ] `npm test`\n- [ ] `npm run build`\n- [ ] {{any feature-specific manual verification, e.g. \"Verified Dashboard 用量页 cache hit card renders with mock data\"}}\n- [ ] {{`npm run test:real` if the change touches upstream protocol}}\n\n## Notes\n\n{{Optional. Use for any of:\n - Reviewer attention requests (\"please double-check the SSE buffer math in src/...\")\n - Known follow-ups (\"memory entry for new RT format will land in a separate PR\")\n - Migration / config impact (\"operators must add `update.allow_prerelease` if they want beta\")\n - Screenshots for UI changes\nRemove this section if there are no notes.}}\n\n## Linked Issues\n\n{{Closes #N / Refs #N — remove if none.}}\n",".claude/skills/pr-push/references/changelog-format.md":"# CHANGELOG Format\n\nCodex-proxy follows [Keep a Changelog](https://keepachangelog.com/). Every PR that changes user-visible behavior, public API, configuration, or build/release infrastructure MUST add an entry to `CHANGELOG.md` under `## [Unreleased]`.\n\n## Section Layout\n\n`## [Unreleased]` contains exactly these subsections (in this order, omit empty ones):\n\n```markdown\n## [Unreleased]\n\n### Changed\n\n- ...\n\n### Added\n\n- ...\n\n### Fixed\n\n- ...\n```\n\n| Subsection | Use for |\n|---|---|\n| `### Added` | New features, new endpoints, new config keys, new CLI flags |\n| `### Changed` | Behavior change of existing features, default value changes, signature changes |\n| `### Fixed` | Bug fixes |\n| `### Removed` | Deleted features (rare; gate behind a deprecation cycle first) |\n| `### Deprecated` | Marking something for future removal |\n| `### Security` | Security-relevant fix (CVE, cred leak, etc.) |\n\n## Entry Style\n\n- Use the same language as the existing `[Unreleased]` entries (zh-CN at time of writing). If the file flips to English, follow.\n- Lead with the user-visible impact, then mention the file paths in parentheses for reviewer navigation.\n- Reference issues / PRs with `(#NNN)` inline.\n- Multi-aspect entries get nested bullets.\n\n## Examples (from current `[Unreleased]`)\n\n```markdown\n### Added\n\n- 图像生成请求计数（成功 / 失败分流）：`AccountUsage` 新增 `image_request_count` / `image_request_failed_count`...\n- Dashboard 用量统计新增「缓存命中率」卡片...\n```\n\n```markdown\n### Changed\n\n- `bump-electron-beta.yml` 触发改为定时 cron（每天 04:00 / 12:00 UTC）...\n```\n\n## When NOT to add a CHANGELOG entry\n\nSkip CHANGELOG for commits that are:\n\n- Test-only (`test:` prefix) — no user impact\n- Doc-only edits to internal docs (`CLAUDE.md`, `.claude/`, `docs/dev-notes/`)\n- Pure refactors that change zero observed behavior (`refactor:` prefix with no API surface change)\n- CI-only changes that do not affect built artifacts (`ci:` prefix)\n- Style/formatting (`style:` prefix)\n\nIf unsure, **add the entry**. A redundant entry is cheaper than a missing one.\n\n## Multi-line / multi-bullet entries\n\nUse the existing nested bullet pattern:\n\n```markdown\n- Ollama bridge cleanup (#403 review followups, closes #405 #406 #407):\n  - `src/ollama/bridge.ts` 不再重复实现 `normalizeHostname`...\n  - `proxyOpenAIRequest` 转发头扩展到...\n  - `MAX_SSE_BUFFER` 重命名为 `MAX_SSE_BUFFER_CHARS`...\n```\n",".claude/skills/pr-push/references/commit-conventions.md":"# Commit Message Conventions\n\nCodex-proxy uses Conventional Commits with a fixed type vocabulary. Several CI workflows pattern-match on the type prefix, so unknown types break automation.\n\n## Format\n\n```\n<type>(<optional scope>): <imperative summary>\n\n<optional body — wrap at ~72 cols, explain WHY>\n\n<optional footer — Closes #N, Refs #N, BREAKING CHANGE: ...>\n```\n\n- Subject is **imperative mood**, lowercase first letter, no trailing period.\n- Subject ≤ 72 chars hard cap.\n- Body explains *why* the change was made, not *what* (the diff shows what).\n\n## Type Vocabulary\n\n| Type | Use for | Triggers beta release? |\n|---|---|---|\n| `feat` | New user-visible feature | yes |\n| `fix` | Bug fix | yes |\n| `perf` | Performance improvement with no behavior change | yes |\n| `refactor` | Code restructuring with no behavior change | no |\n| `docs` | Documentation only | no |\n| `test` | Test-only changes | no |\n| `chore` | Tooling, dependencies, repo housekeeping | no |\n| `ci` | CI/CD configuration | no |\n| `style` | Formatting, whitespace, no logic change | no |\n\nThe \"Triggers beta release?\" column is determined by `bump-electron-beta.yml`'s skip filter: `^(chore|docs|ci|test|refactor|style)`. Note that `fix(ci):` still triggers a beta release because the prefix is `fix`.\n\n## Scope\n\nOptional, but encouraged for clarity. Use the top-level module name:\n\n- `feat(auth): ...`\n- `fix(translation): ...`\n- `refactor(routes): ...`\n- `chore(deps): ...`\n- `ci(release): ...`\n\nSkip the scope when the change spans multiple modules or is genuinely repo-wide.\n\n## Examples\n\nGood:\n\n```\nfeat(auth): persist account-pool RT-only imports across restarts\n```\n\n```\nfix(translation): recover from previous_response_not_found instead of passing it through\n```\n\n```\nrefactor(routes): extract shared proxy-handler from openai/anthropic/gemini handlers\n```\n\nBad — and why:\n\n| Message | Why it fails |\n|---|---|\n| `Update auth.ts` | No type, describes WHAT not WHY |\n| `feat: Added new feature.` | Past tense + capitalized + trailing period |\n| `feature(auth): persist RT` | `feature` is not in the vocabulary, use `feat` |\n| `fix: stuff` | Subject is meaningless |\n| `wip` | No type, no information |\n\n## Multi-line body\n\nUse a HEREDOC to preserve formatting:\n\n```bash\ngit commit -m \"$(cat <<'EOF'\nfix(quota): ignore stale x-codex-* headers after token refresh\n\nThe previous behavior overwrote fresh quota state with cached headers\nfrom the old token, causing accounts to appear over-quota for ~30s\nafter refresh. Now we drop quota updates whose token id does not match\nthe current session.\n\nCloses #418\nEOF\n)\"\n```\n",".claude/skills/pr-push/references/pr-checklist.md":"# Pre-PR Self-Check\n\nWalk this list before opening the PR. Anything left unchecked needs a written reason in the PR body.\n\n## Branch & target\n\n- [ ] Current branch is NOT `dev`, `master`, or `main`\n- [ ] Branch is rebased on (or fast-forwardable to) `origin/dev`\n- [ ] PR target = `dev`\n\n## Commit hygiene\n\n- [ ] Each commit follows `<type>(<scope>): <summary>` with a vocabulary type (see `commit-conventions.md`)\n- [ ] No commit was created with `--no-verify`\n- [ ] No file added with `git add -f`\n- [ ] No accidental staging of `node_modules/`, `dist/`, `*.log`, `.env*`, `data/`, or other gitignored paths\n- [ ] No secrets in code or commit messages (API keys, tokens, cookies, oauth_state)\n\n## CHANGELOG\n\n- [ ] If the change touches `src/`, `shared/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` → `CHANGELOG.md` `[Unreleased]` has a new entry\n- [ ] Entry placed in correct subsection (Added / Changed / Fixed)\n- [ ] Entry references the issue / PR number when applicable\n\n## Cross-artifact impact\n\nCodex-proxy ships three artifacts: backend (Docker), Electron desktop, web frontend. The pre-push hook will catch most of these, but verify mentally first:\n\n- [ ] If `src/` changed → backend logic still passes `npm test`\n- [ ] If `web/` changed → `npm run build` produces a clean Vite bundle\n- [ ] If `Dockerfile` / `docker-compose*` changed → image still builds\n- [ ] If `packages/electron/**` or `electron-builder.yml` changed → Electron config validates\n- [ ] If `native/**` changed → native addon still builds\n\n## Tests\n\n- [ ] New behavior has new tests (TDD: tests written first when feasible)\n- [ ] All affected `npm test` suites pass locally\n- [ ] No `*.skip` left behind unless explicitly justified in the PR body\n\n## TypeScript\n\n- [ ] No `any`, `as any`, `: any`, or `<any>` in new code (use `unknown`, generics, or specific types)\n- [ ] No `@ts-ignore` / `@ts-expect-error` without an inline explanation comment\n\n## Real-upstream changes\n\n- [ ] If the change touches the upstream protocol (translation/, proxy/, auth/), `npm run test:real` was attempted at least once\n\n## Documentation\n\n- [ ] Public-facing config/flag changes are reflected in `config/default.yaml` comments and `CLAUDE.md` if relevant\n- [ ] No internal personal notes leaked into committed files\n\n## After push (do NOT do these in this skill)\n\n- [ ] Wait for CI green before requesting review\n- [ ] Merge is a separate, explicit decision — never auto-merge from this skill\n","AGENTS.md":"## 多 Agent 工作流\n\n- 仅在用户明确授权或任务明确要求时启用；完整规则见 `docs/MULTI_AGENT_WORKFLOW.md`。\n- 默认在满足最低安全和验收要求的前提下，优先减少总 token、credits、费用与重复阅读。\n- 开工前按语义难度、修改范围、可验证性、失败后果和上下文负担预分类。\n- 使用预计可完成任务的最低成本执行体；高性能执行体只用于关键推理、弱机械验收或高后果节点。\n- 简单任务不为使用多 Agent 增加调度成本；并行优先用于互不重叠的只读工作。\n- 同一工作树和合同域保持单写者；Reviewer/Verifier 默认只读。\n- 子 Agent 使用最小上下文、稳定公共前缀与增量证据，避免完整历史复制和重复读取。\n- 多 Agent 授权不扩大网络、真实 API、外部写入、提交、发布或破坏性操作权限。\n- 达到当前任务验收或停止条件后立即停止，不自动进入下一票据。\n\n## Gemini / Antigravity Schema 与日志\n\n- Gemini / Antigravity 的工具参数及结构化输出 schema 必须按 Gemini 支持的字段白名单清洗；清除 `prefixItems` 等不支持字段后，如果 schema 仍为 `type: array` 且缺少 `items`，需补宽松的 `{}` schema，避免 Gemini 的 `missing field` 校验错误。为此类变换补充嵌套 schema 回归测试。\n- 持久化请求/错误诊断时，必须先脱敏并限制单条记录和文件大小；不要提交临时的原始 tools / request dump，也不要记录凭据。\n\n## Keepalive safety\n\n- Account keepalive is disabled by default. Enabling the scheduler or calling `POST /admin/keepalive-run` sends real requests to `/codex/usage`; unit tests must mock `CodexApi`, and real-account execution requires explicit user authorization.\n","packages/npm/README.md":"# @icebear0828/codex-proxy\n\nOpenAI-compatible proxy for the ChatGPT Codex Responses API, with a web dashboard, a multi-account key pool and an Ollama-compatible bridge. This is the full application — dashboard, account management and the Ollama bridge all work the same as the desktop and Docker versions.\n\n## Install\n\nRequires Node.js 22.13+ (uses the built-in `node:sqlite`).\n\nThis package is published to GitHub Packages, not to the public npmjs registry. Installing it from GitHub Packages needs an npm auth token with `read:packages`:\n\n```ini\n@icebear0828:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\n```\n\n```bash\nnpm install -g @icebear0828/codex-proxy\n```\n\nNo-auth alternative: download `codex-proxy-npm.zip` from the [latest release](https://github.com/icebear0828/codex-proxy/releases/latest/download/codex-proxy-npm.zip), extract it and run `node install.mjs` inside the extracted directory.\n\n## Run\n\n```bash\ncodex-proxy            # starts the server and opens the dashboard\ncodex-proxy --mode=server   # headless server only\ncodex-proxy --mode=browser  # force the system browser\ncodex-proxy --help          # all options\n```\n\nOn first start the dashboard opens at `http://127.0.0.1:8080` (port configurable via `--port` or `PORT`). On Windows the dashboard opens in your system browser; the desktop app and the Lite zip ship a native WebView2 host, which the npm package does not include.\n\nRuntime data (accounts, config, usage history) is stored in the per-user data directory (`%APPDATA%\\@codex-proxy\\electron\\data` on Windows, `~/.config/@codex-proxy/electron/data` on Linux, `~/Library/Application Support/@codex-proxy/electron/data` on macOS), so it survives package updates. Set `CODEX_PROXY_DATA_DIR` or pass `--portable` to relocate it. Platform-specific TLS addons are installed automatically for your OS/architecture; binaries for other platforms are never downloaded.\n\n## Links\n\n- [GitHub repository](https://github.com/icebear0828/codex-proxy)\n- [Documentation & screenshots](https://github.com/icebear0828/codex-proxy#readme)\n- Desktop installers, the portable zip and Docker images are published on the [releases page](https://github.com/icebear0828/codex-proxy/releases).\n\n## License\n\nNon-commercial licence — see [LICENCE](https://github.com/icebear0828/codex-proxy/blob/dev/LICENCE).\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"## 多 Agent 工作流\n\n- 仅在用户明确授权或任务明确要求时启用；完整规则见 `docs/MULTI_AGENT_WORKFLOW.md`。\n- 默认在满足最低安全和验收要求的前提下，优先减少总 token、credits、费用与重复阅读。\n- 开工前按语义难度、修改范围、可验证性、失败后果和上下文负担预分类。\n- 使用预计可完成任务的最低成本执行体；高性能执行体只用于关键推理、弱机械验收或高后果节点。\n- 简单任务不为使用多 Agent 增加调度成本；并行优先用于互不重叠的只读工作。\n- 同一工作树和合同域保持单写者；Reviewer/Verifier 默认只读。\n- 子 Agent 使用最小上下文、稳定公共前缀与增量证据，避免完整历史复制和重复读取。\n- 多 Agent 授权不扩大网络、真实 API、外部写入、提交、发布或破坏性操作权限。\n- 达到当前任务验收或停止条件后立即停止，不自动进入下一票据。\n\n## Gemini / Antigravity Schema 与日志\n\n- Gemini / Antigravity 的工具参数及结构化输出 schema 必须按 Gemini 支持的字段白名单清洗；清除 `prefixItems` 等不支持字段后，如果 schema 仍为 `type: array` 且缺少 `items`，需补宽松的 `{}` schema，避免 Gemini 的 `missing field` 校验错误。为此类变换补充嵌套 schema 回归测试。\n- 持久化请求/错误诊断时，必须先脱敏并限制单条记录和文件大小；不要提交临时的原始 tools / request dump，也不要记录凭据。\n\n## Keepalive safety\n\n- Account keepalive is disabled by default. Enabling the scheduler or calling `POST /admin/keepalive-run` sends real requests to `/codex/usage`; unit tests must mock `CodexApi`, and real-account execution requires explicit user authorization.\n","isInternal":false,"tokens":576,"sizeBytes":1805},{"name":"bug-report.md","path":".agents/skills/issue-create/assets/bug-report.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.agents/skills/issue-create/assets/bug-report.md","title":"Assets Skill","category":"anthropic-skill","format":"markdown","content":"<!--\nBug report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nMatch the language of the repo's existing issues (currently a mix of zh-CN and en).\n-->\n\n## Summary\n\n{{One sentence describing the bug.}}\n\n## Expected behavior\n\n{{What the user thought would happen.}}\n\n## Actual behavior\n\n{{What actually happened.}}\n\n## Reproduction steps\n\n1. {{step 1}}\n2. {{step 2}}\n3. {{step 3 — describe the failure}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| Frequency | {{always / intermittent / once}} |\n| First broken version (if known) | {{version or \"unknown\"}} |\n| Workaround (if any) | {{description or \"none\"}} |\n\n## Logs / output\n\n```\n{{Paste relevant log lines. SECRETS REDACTED — no tokens, cookies,\noauth_state, API keys, account IDs.}}\n```\n\n## Additional context\n\n{{Anything else the maintainer should know. Remove this section if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n","isInternal":false,"tokens":291,"sizeBytes":1104},{"name":"feature-request.md","path":".agents/skills/issue-create/assets/feature-request.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.agents/skills/issue-create/assets/feature-request.md","title":"Assets Skill","category":"anthropic-skill","format":"markdown","content":"<!--\nFeature request template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\n-->\n\n## Summary\n\n{{One sentence describing the feature.}}\n\n## Problem\n\n{{The user-facing motivation. What can the user not do today, or what is\npainful about how they have to do it? DO NOT describe the proposed\nsolution here — only the problem.}}\n\n## Proposed solution\n\n{{High-level description of how the feature would work. Implementation\ndetail is welcome but not required. If you have a UI in mind, sketch\nor screenshot helps.}}\n\n## Alternatives considered\n\n{{Other approaches the user thought about and why they don't fit.\nEven \"I considered X but it doesn't work because Y\" is useful — it\nsaves the maintainer from re-deriving the same conclusion.}}\n\n## Who benefits\n\n{{single user / all users / a specific deployment mode (Electron / Docker / dev) /\na specific upstream provider / a specific account state}}\n\n## Impact if not done\n\n{{Does the user have a workaround? Is this blocking? Nice-to-have?\nRemove this section if \"no impact, just nice\".}}\n\n## Additional context\n\n{{Mockups, links, related discussions. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n","isInternal":false,"tokens":272,"sizeBytes":1205},{"name":"perf-report.md","path":".agents/skills/issue-create/assets/perf-report.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.agents/skills/issue-create/assets/perf-report.md","title":"Assets Skill","category":"anthropic-skill","format":"markdown","content":"<!--\nPerformance report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nA perf report without numbers is just a bug — switch to bug-report.md if\nno measurements are available.\n-->\n\n## Summary\n\n{{One sentence describing the regression or slowness.}}\n\n## Expected behavior\n\n{{What performance was expected, and where that expectation comes from\n(prior version, docs, comparable system).}}\n\n## Actual behavior\n\n{{What is observed instead.}}\n\n## Measurements\n\n| Metric | Baseline | Current | Delta |\n|---|---|---|---|\n| {{e.g. p95 latency}} | {{200ms}} | {{1.4s}} | {{+600%}} |\n| {{e.g. memory RSS}} | {{180MB}} | {{420MB}} | {{+133%}} |\n\n**Methodology:** {{How the numbers were taken — script, manual stopwatch,\nprofiler, load test. Be specific enough that a maintainer can reproduce.}}\n\n## Reproduction harness\n\n```\n{{Script, `tests/bench/...` reference, or numbered steps. Must be\ndeterministic enough to re-measure.}}\n```\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| First slow version (if known) | {{version or \"unknown\"}} |\n| Resource constraint hit | {{CPU / memory / network / FDs / \"none\"}} |\n\n## Logs / output\n\n```\n{{Relevant log lines or profiler output. SECRETS REDACTED.}}\n```\n\n## Additional context\n\n{{Anything else. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n","isInternal":false,"tokens":404,"sizeBytes":1508},{"name":"question.md","path":".agents/skills/issue-create/assets/question.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.agents/skills/issue-create/assets/question.md","title":"Assets Skill","category":"anthropic-skill","format":"markdown","content":"<!--\nQuestion template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nNote: if it turns out to be a bug, switch to the bug-report template.\n-->\n\n## What I'm trying to accomplish\n\n{{The end goal, not the immediate confusion. e.g. \"I want to route\ngpt-5.5 traffic only to my work account\" — not \"what does\nplan_mapping do?\"}}\n\n## What I tried\n\n{{Commands, config snippets, docs read, search terms used. Be specific.}}\n\n```yaml\n# Relevant config — SECRETS REDACTED\n{{config snippet or \"none\"}}\n```\n\n## What I expected\n\n{{What outcome did you anticipate?}}\n\n## What happened\n\n{{What did you actually observe?}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n\n## Additional context\n\n{{Logs, screenshots, anything else. Remove if empty.}}\n","isInternal":false,"tokens":243,"sizeBytes":909},{"name":"issue-types.md","path":".agents/skills/issue-create/references/issue-types.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.agents/skills/issue-create/references/issue-types.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Issue Type Specs\n\nRequired and optional fields per issue type. The skill enforces \"required\" — every required field must have either an answer or an explicit \"not applicable\" / \"unknown\" before the issue can be filed.\n\n## Bug\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Becomes part of the title; ≤72 chars |\n| Expected behavior | yes | What the user thought would happen |\n| Actual behavior | yes | What actually happened |\n| Reproduction steps | yes | Numbered list, deterministic |\n| Codex-proxy version | yes | `npm pkg get version` or About dialog |\n| Deployment mode | yes | Electron / Docker / `npm start` / dev / source |\n| OS + arch | yes | e.g. macOS 14.5 arm64, Windows 11 x64, Ubuntu 22.04 x64 |\n| Relevant logs | yes | Redact secrets; \"none\" is acceptable |\n| Frequency | yes | always / intermittent / once |\n| Workaround | no | If the user found one |\n| First broken version | no | If known (helps bisect) |\n| Related issues | no | `Refs #N` |\n\n## Feature Request\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Title material |\n| Problem statement | yes | The user-facing motivation. NOT the proposed solution. |\n| Proposed solution | yes | High level; implementation detail is welcome but optional |\n| Alternatives considered | yes | Even \"I considered X but it doesn't fit because Y\" |\n| Who benefits | yes | single user / all users / specific deployment mode / specific upstream |\n| Impact if NOT done | no | Does the user have a workaround? Is this blocking? |\n| Related issues / PRs | no | `Refs #N` |\n| Mockups / sketches | no | For UI features |\n\n## Question\n\n| Field | Required | Notes |\n|---|---|---|\n| What you're trying to accomplish | yes | The end goal, not the immediate confusion |\n| What you tried | yes | Commands, config, links to docs read |\n| What you expected | yes | |\n| What happened | yes | |\n| Relevant config | yes | Redact secrets; \"none\" if no config involved |\n| Codex-proxy version | yes | |\n| Deployment mode | yes | |\n\nIf a \"question\" turns out to be a bug during the interview, switch to the Bug template — do not file under `question`.\n\n## Performance\n\nAll Bug fields, plus:\n\n| Field | Required | Notes |\n|---|---|---|\n| Baseline measurement | yes | Numbers from a known-good version or expected baseline |\n| Current measurement | yes | Same metric, current version |\n| Measurement methodology | yes | How the numbers were taken — script, manual stopwatch, profiler |\n| Reproduction harness | yes | Script, `tests/bench/...` reference, or steps |\n| Resource constraint hit | no | CPU, memory, network, file descriptors, etc. |\n\nA perf report without numbers is a bug report — switch templates.\n\n## Documentation\n\n| Field | Required | Notes |\n|---|---|---|\n| Doc location | yes | File path (`README.md`, `CLAUDE.md`, `docs/...`) or URL |\n| What is wrong / missing | yes | Specific quote of the offending text, or \"this section is missing\" |\n| Suggested fix | no | Welcome but not required |\n| Audience affected | no | New users / operators / contributors / API consumers |\n","isInternal":false,"tokens":750,"sizeBytes":3083},{"name":"labels.md","path":".agents/skills/issue-create/references/labels.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.agents/skills/issue-create/references/labels.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Issue Labels (codex-proxy)\n\nThe complete catalog of labels currently defined on the repo. Apply only labels from this list — do not invent new ones. To propose a new label, file a `chore:` issue separately.\n\n| Label | Color | Use for |\n|---|---|---|\n| `bug` | #d73a4a | Something isn't working as documented or intended |\n| `enhancement` | #a2eeef | New feature or extension of an existing feature |\n| `documentation` | #0075ca | Improvements or additions to documentation |\n| `question` | #d876e3 | Further information is requested; not yet known to be a bug |\n| `help wanted` | #008672 | Maintainers welcome contributors to take this on |\n| `good first issue` | #7057ff | Small scope, low context required, friendly to newcomers |\n| `duplicate` | #cfd3d7 | Already filed elsewhere — set after triage, not on creation |\n| `invalid` | #e4e669 | Not actionable or out of scope — set after triage |\n| `wontfix` | #ffffff | Acknowledged but will not be addressed — set after triage |\n| `sync-conflict` | #d73a4a | `main → electron` auto-sync merge conflict — used by automation, not for human-filed issues |\n\n## Application rules for the skill\n\n1. **One type label minimum**: bug / enhancement / documentation / question (pick exactly one based on the issue type).\n2. **`good first issue`**: only when the user explicitly confirms the scope is small AND the fix is local (single file or single module).\n3. **`help wanted`**: when the reporter has no plan to send a PR themselves.\n4. **`documentation`** can be combined with `bug` or `enhancement` if the change requires both code and doc updates.\n5. **Never apply on creation**: `duplicate`, `invalid`, `wontfix`, `sync-conflict`. These are triage / automation labels.\n\n## CLI form\n\n```bash\ngh issue create --label \"bug,help wanted\" ...\n```\n\nMultiple labels are comma-separated (no space after the comma).\n","isInternal":false,"tokens":471,"sizeBytes":1867},{"name":"SKILL.md","path":".agents/skills/issue-create/SKILL.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.agents/skills/issue-create/SKILL.md","title":"issue-create","category":"anthropic-skill","format":"markdown","content":"---\nname: issue-create\ndescription: >-\n  Interview the user to gather all required context, then open a high-quality GitHub issue (`gh issue create`) on the codex-proxy repo with the right template, labels, and structured body.\n  TRIGGER when: user says \"open an issue\", \"file an issue\", \"create issue\", \"report a bug\", \"feature request\", \"提个 issue\", \"报 bug\", \"提需求\".\n  DO NOT TRIGGER when: user wants to view, search, comment on, or close existing issues (use `gh issue list/view/comment/close` directly); user is writing a PR description (use `pr-push`).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Write\"\n---\n\n# Issue Create\n\nGather complete context through a structured interview, then file a well-formed issue. The interview is a hard gate — vague issues waste maintainer time.\n\n## Overview\n\nMost \"I have a bug\" or \"I want a feature\" reports are missing the information a maintainer needs to act. This skill runs a four-phase interview, fills the appropriate template, applies the right labels, and only then calls `gh issue create`. The user sees and approves the rendered body before submission.\n\n## When to Use\n\n- A user wants to file a new issue on the codex-proxy repository.\n- A user describes a bug or feature in conversation and asks \"should we file an issue?\"\n\n## Important Rules\n\n1. **The interview is not optional.** Do NOT call `gh issue create` until all required fields for the chosen type are collected and the user has explicitly approved the rendered body.\n2. **Never invent reproduction steps, version numbers, log output, or behavior.** If the user did not provide it, ask. If they cannot provide it, write \"not provided\" in the field, do not fabricate.\n3. **Show the full body before submitting.** The user must explicitly say \"submit\" / \"looks good\" / equivalent. \"Yes\" without seeing the body is not enough — show it first.\n4. **Apply only labels from the project's existing label set.** Read `references/labels.md` for the catalog. Do not invent new labels.\n5. **Strip secrets.** If the user pastes logs, headers, or config that contain tokens, cookies, OAuth state, API keys, or account IDs, redact them before they enter the issue body. Replace with `<redacted>`.\n6. **One issue per scope.** If the user describes two unrelated problems, file two issues. Ask before splitting.\n\n## Key Workflows\n\n### Phase 1: Type classification\n\n**Goal:** Pick the right template and label.\n\nAsk the user (one consolidated question):\n\n> What type of issue is this?\n>   1. **Bug** — something is broken or behaves incorrectly\n>   2. **Feature request** — propose new functionality\n>   3. **Question** — usage / configuration / \"is this expected?\"\n>   4. **Performance** — measurable regression or slowness\n>   5. **Documentation** — docs are wrong, missing, or unclear\n\nRead the type spec:\n```\nRead: .Codex/skills/issue-create/references/issue-types.md\n```\n\nMap answer to template path:\n\n| Type | Template asset | Default label |\n|---|---|---|\n| Bug | `assets/bug-report.md` | `bug` |\n| Feature request | `assets/feature-request.md` | `enhancement` |\n| Question | `assets/question.md` | `question` |\n| Performance | `assets/perf-report.md` | `bug` |\n| Documentation | `assets/feature-request.md` (with docs framing) | `documentation` |\n\nDo **NOT** proceed to Phase 2 until the type is confirmed.\n\n### Phase 2: Required-field interview\n\n**Goal:** Collect every field the chosen template requires.\n\nRead `references/issue-types.md` to see the required-field table for the chosen type. Ask for missing fields in **one consolidated message**, not one at a time. Group related fields together.\n\n**For bugs**, the required fields are:\n- One-line summary\n- Expected behavior\n- Actual behavior\n- Reproduction steps (numbered)\n- Codex-proxy version (`npm pkg get version` or app About dialog)\n- Deployment mode (Electron app / Docker / `npm start` / dev)\n- Relevant log lines (redact secrets)\n- Frequency (always / intermittent / once)\n\n**For feature requests**, the required fields are:\n- Problem the feature solves (user-facing motivation, not the proposed solution)\n- Proposed solution (high level)\n- Alternatives considered\n- Who benefits (single user / all users / specific deployment mode)\n\n**For questions**:\n- What you tried\n- What you expected\n- What happened\n- Relevant config (redact secrets)\n\n**For performance**:\n- All bug fields, plus:\n- Measured baseline vs current (timings, memory, request count — be specific)\n- Reproduction harness (script, steps, or `tests/bench/`)\n\n**For documentation**:\n- Which doc page / file\n- What is wrong or missing\n- Suggested fix (if any)\n\nIf a field cannot be answered, the user must explicitly say \"not applicable\" or \"unknown\" — record that verbatim. Do not silently skip.\n\nDo **NOT** proceed to Phase 3 until every required field has either an answer or an explicit \"not applicable\".\n\n### Phase 3: Code & related-context grounding\n\n**Goal:** Help maintainers find the relevant code fast.\n\nAsk the user for:\n- File paths or `file:line` references they suspect are involved (optional but encouraged).\n- Related issues / PRs to link (`Refs #N`, `Related to #N`).\n- Whether they tried searching existing issues (`gh issue list --search \"<keywords>\"`). If they have not and the report sounds like something that might exist, run the search and show top 3 matches before continuing.\n\nIf the user provides no code locations and the bug is concrete, optionally offer:\n> \"Want me to grep for the relevant code so we can include file:line in the issue?\"\n\nDo not grep silently — ask first, and only do it once.\n\n### Phase 4: Render, confirm, submit\n\n**Goal:** Show the final body, get explicit approval, file the issue.\n\n1. Read the chosen template:\n   ```\n   Read: .Codex/skills/issue-create/assets/<template>.md\n   ```\n2. Read the labels catalog:\n   ```\n   Read: .Codex/skills/issue-create/references/labels.md\n   ```\n3. Fill the template with the collected fields. Strip secrets per Important Rule #5.\n4. Pick labels:\n   - Always include the type label (Phase 1 mapping).\n   - Add `good first issue` only if the user explicitly says it qualifies (small scope, low context required).\n   - Add `help wanted` if the user has no plan to fix it themselves.\n   - Add `documentation` in addition to the type label if docs need updating.\n5. Show the user the complete rendered output:\n   ```\n   Title: <title>\n   Labels: <label1>, <label2>\n   Body:\n   <full body>\n   ```\n6. Ask: \"Ready to submit, or want to adjust anything?\"\n7. Wait for an explicit affirmative. \"Yes\", \"submit\", \"go\", \"looks good\", \"提交\" all qualify. Silence or hedging does not.\n8. Submit:\n   ```bash\n   gh issue create \\\n     --title \"<title>\" \\\n     --label \"<label1>,<label2>\" \\\n     --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n9. Print the issue URL.\n10. **STOP.** Do not assign, do not comment, do not link to projects unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not call `gh issue create` before showing the body for approval.\n- Do not invent reproduction steps when the user gave a vague report — ask.\n- Do not paste raw logs that contain tokens / cookies / OAuth state / account IDs.\n- Do not apply labels outside the existing catalog.\n- Do not file two issues from one report without confirming the split with the user.\n- Do not grep / search the codebase silently to \"fill in\" missing fields — ask first.\n","frontmatter":{"name":"issue-create","description":"Interview the user to gather all required context, then open a high-quality GitHub issue (`gh issue create`) on the codex-proxy repo with the right template, labels, and structured body. TRIGGER when: user says \"open an issue\", \"file an issue\", \"create issue\", \"report a bug\", \"feature request\", \"提个 issue\", \"报 bug\", \"提需求\". DO NOT TRIGGER when: user wants to view, search, comment on, or close existing issues (use `gh issue list/view/comment/close` directly); user is writing a PR description (use `pr-push`).","allowed-tools":["Bash","Read","Write"],"allowedTools":["Bash","Read","Write"]},"allowedTools":["Bash","Read","Write"],"isInternal":false,"tokens":1771,"sizeBytes":7402},{"name":"pr-body-template.md","path":".agents/skills/pr-push/assets/pr-body-template.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.agents/skills/pr-push/assets/pr-body-template.md","title":"Assets Skill","category":"anthropic-skill","format":"markdown","content":"<!--\nPR body template for codex-proxy. The skill fills in the {{placeholders}}\nand removes optional sections that don't apply. Default language follows\nthe repo's dominant language (currently zh-CN for CHANGELOG entries,\nen for code/commits). Pick one and stay consistent within a single PR.\n-->\n\n## Summary\n\n{{One paragraph: WHAT changed and WHY. Reference the user-visible impact.\nIf multiple commits, summarize the branch's intent, not each commit.}}\n\n## Changes\n\n{{Bulleted list mirroring the CHANGELOG entry. Group by area when the PR\ntouches multiple modules. Reference file paths so reviewers can navigate.}}\n\n- {{change 1 — files}}\n- {{change 2 — files}}\n\n## Test Plan\n\n{{List the commands actually run locally. Do not invent results.\nMark checked items with [x], unchecked with [ ].}}\n\n- [ ] `npm test`\n- [ ] `npm run build`\n- [ ] {{any feature-specific manual verification, e.g. \"Verified Dashboard 用量页 cache hit card renders with mock data\"}}\n- [ ] {{`npm run test:real` if the change touches upstream protocol}}\n\n## Notes\n\n{{Optional. Use for any of:\n - Reviewer attention requests (\"please double-check the SSE buffer math in src/...\")\n - Known follow-ups (\"memory entry for new RT format will land in a separate PR\")\n - Migration / config impact (\"operators must add `update.allow_prerelease` if they want beta\")\n - Screenshots for UI changes\nRemove this section if there are no notes.}}\n\n## Linked Issues\n\n{{Closes #N / Refs #N — remove if none.}}\n","isInternal":false,"tokens":340,"sizeBytes":1475},{"name":"changelog-format.md","path":".agents/skills/pr-push/references/changelog-format.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.agents/skills/pr-push/references/changelog-format.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# CHANGELOG Format\n\nCodex-proxy follows [Keep a Changelog](https://keepachangelog.com/). Every PR that changes user-visible behavior, public API, configuration, or build/release infrastructure MUST add an entry to `CHANGELOG.md` under `## [Unreleased]`.\n\n## Section Layout\n\n`## [Unreleased]` contains exactly these subsections (in this order, omit empty ones):\n\n```markdown\n## [Unreleased]\n\n### Changed\n\n- ...\n\n### Added\n\n- ...\n\n### Fixed\n\n- ...\n```\n\n| Subsection | Use for |\n|---|---|\n| `### Added` | New features, new endpoints, new config keys, new CLI flags |\n| `### Changed` | Behavior change of existing features, default value changes, signature changes |\n| `### Fixed` | Bug fixes |\n| `### Removed` | Deleted features (rare; gate behind a deprecation cycle first) |\n| `### Deprecated` | Marking something for future removal |\n| `### Security` | Security-relevant fix (CVE, cred leak, etc.) |\n\n## Entry Style\n\n- Use the same language as the existing `[Unreleased]` entries (zh-CN at time of writing). If the file flips to English, follow.\n- Lead with the user-visible impact, then mention the file paths in parentheses for reviewer navigation.\n- Reference issues / PRs with `(#NNN)` inline.\n- Multi-aspect entries get nested bullets.\n\n## Examples (from current `[Unreleased]`)\n\n```markdown\n### Added\n\n- 图像生成请求计数（成功 / 失败分流）：`AccountUsage` 新增 `image_request_count` / `image_request_failed_count`...\n- Dashboard 用量统计新增「缓存命中率」卡片...\n```\n\n```markdown\n### Changed\n\n- `bump-electron-beta.yml` 触发改为定时 cron（每天 04:00 / 12:00 UTC）...\n```\n\n## When NOT to add a CHANGELOG entry\n\nSkip CHANGELOG for commits that are:\n\n- Test-only (`test:` prefix) — no user impact\n- Doc-only edits to internal docs (`CLAUDE.md`, `.claude/`, `docs/dev-notes/`)\n- Pure refactors that change zero observed behavior (`refactor:` prefix with no API surface change)\n- CI-only changes that do not affect built artifacts (`ci:` prefix)\n- Style/formatting (`style:` prefix)\n\nIf unsure, **add the entry**. A redundant entry is cheaper than a missing one.\n\n## Multi-line / multi-bullet entries\n\nUse the existing nested bullet pattern:\n\n```markdown\n- Ollama bridge cleanup (#403 review followups, closes #405 #406 #407):\n  - `src/ollama/bridge.ts` 不再重复实现 `normalizeHostname`...\n  - `proxyOpenAIRequest` 转发头扩展到...\n  - `MAX_SSE_BUFFER` 重命名为 `MAX_SSE_BUFFER_CHARS`...\n```\n","isInternal":false,"tokens":633,"sizeBytes":2454},{"name":"commit-conventions.md","path":".agents/skills/pr-push/references/commit-conventions.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.agents/skills/pr-push/references/commit-conventions.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Commit Message Conventions\n\nCodex-proxy uses Conventional Commits with a fixed type vocabulary. Several CI workflows pattern-match on the type prefix, so unknown types break automation.\n\n## Format\n\n```\n<type>(<optional scope>): <imperative summary>\n\n<optional body — wrap at ~72 cols, explain WHY>\n\n<optional footer — Closes #N, Refs #N, BREAKING CHANGE: ...>\n```\n\n- Subject is **imperative mood**, lowercase first letter, no trailing period.\n- Subject ≤ 72 chars hard cap.\n- Body explains *why* the change was made, not *what* (the diff shows what).\n\n## Type Vocabulary\n\n| Type | Use for | Triggers beta release? |\n|---|---|---|\n| `feat` | New user-visible feature | yes |\n| `fix` | Bug fix | yes |\n| `perf` | Performance improvement with no behavior change | yes |\n| `refactor` | Code restructuring with no behavior change | no |\n| `docs` | Documentation only | no |\n| `test` | Test-only changes | no |\n| `chore` | Tooling, dependencies, repo housekeeping | no |\n| `ci` | CI/CD configuration | no |\n| `style` | Formatting, whitespace, no logic change | no |\n\nThe \"Triggers beta release?\" column is determined by `bump-electron-beta.yml`'s skip filter: `^(chore|docs|ci|test|refactor|style)`. Note that `fix(ci):` still triggers a beta release because the prefix is `fix`.\n\n## Scope\n\nOptional, but encouraged for clarity. Use the top-level module name:\n\n- `feat(auth): ...`\n- `fix(translation): ...`\n- `refactor(routes): ...`\n- `chore(deps): ...`\n- `ci(release): ...`\n\nSkip the scope when the change spans multiple modules or is genuinely repo-wide.\n\n## Examples\n\nGood:\n\n```\nfeat(auth): persist account-pool RT-only imports across restarts\n```\n\n```\nfix(translation): recover from previous_response_not_found instead of passing it through\n```\n\n```\nrefactor(routes): extract shared proxy-handler from openai/anthropic/gemini handlers\n```\n\nBad — and why:\n\n| Message | Why it fails |\n|---|---|\n| `Update auth.ts` | No type, describes WHAT not WHY |\n| `feat: Added new feature.` | Past tense + capitalized + trailing period |\n| `feature(auth): persist RT` | `feature` is not in the vocabulary, use `feat` |\n| `fix: stuff` | Subject is meaningless |\n| `wip` | No type, no information |\n\n## Multi-line body\n\nUse a HEREDOC to preserve formatting:\n\n```bash\ngit commit -m \"$(cat <<'EOF'\nfix(quota): ignore stale x-codex-* headers after token refresh\n\nThe previous behavior overwrote fresh quota state with cached headers\nfrom the old token, causing accounts to appear over-quota for ~30s\nafter refresh. Now we drop quota updates whose token id does not match\nthe current session.\n\nCloses #418\nEOF\n)\"\n```\n","isInternal":false,"tokens":670,"sizeBytes":2605},{"name":"pr-checklist.md","path":".agents/skills/pr-push/references/pr-checklist.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.agents/skills/pr-push/references/pr-checklist.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Pre-PR Self-Check\n\nWalk this list before opening the PR. Anything left unchecked needs a written reason in the PR body.\n\n## Branch & target\n\n- [ ] Current branch is NOT `dev` or `main`\n- [ ] Branch is rebased on (or fast-forwardable to) `origin/dev`\n- [ ] PR target = `dev`\n\n## Commit hygiene\n\n- [ ] Each commit follows `<type>(<scope>): <summary>` with a vocabulary type (see `commit-conventions.md`)\n- [ ] No commit was created with `--no-verify`\n- [ ] No file added with `git add -f`\n- [ ] No accidental staging of `node_modules/`, `dist/`, `*.log`, `.env*`, `data/`, or other gitignored paths\n- [ ] No secrets in code or commit messages (API keys, tokens, cookies, oauth_state)\n\n## CHANGELOG\n\n- [ ] If the change touches `src/`, `shared/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` → `CHANGELOG.md` `[Unreleased]` has a new entry\n- [ ] Entry placed in correct subsection (Added / Changed / Fixed)\n- [ ] Entry references the issue / PR number when applicable\n\n## Cross-artifact impact\n\nCodex-proxy ships three artifacts: backend (Docker), Electron desktop, web frontend. The pre-push hook will catch most of these, but verify mentally first:\n\n- [ ] If `src/` changed → backend logic still passes `npm test`\n- [ ] If `web/` changed → `npm run build` produces a clean Vite bundle\n- [ ] If `Dockerfile` / `docker-compose*` changed → image still builds\n- [ ] If `packages/electron/**` or `electron-builder.yml` changed → Electron config validates\n- [ ] If `native/**` changed → native addon still builds\n\n## Tests\n\n- [ ] New behavior has new tests (TDD: tests written first when feasible)\n- [ ] All affected `npm test` suites pass locally\n- [ ] No `*.skip` left behind unless explicitly justified in the PR body\n\n## TypeScript\n\n- [ ] No `any`, `as any`, `: any`, or `<any>` in new code (use `unknown`, generics, or specific types)\n- [ ] No `@ts-ignore` / `@ts-expect-error` without an inline explanation comment\n\n## Real-upstream changes\n\n- [ ] If the change touches the upstream protocol (translation/, proxy/, auth/), `npm run test:real` was attempted at least once\n\n## Documentation\n\n- [ ] Public-facing config/flag changes are reflected in `config/default.yaml` comments and `CLAUDE.md` if relevant\n- [ ] No internal personal notes leaked into committed files\n\n## After push (do NOT do these in this skill)\n\n- [ ] Wait for CI green before requesting review\n- [ ] Merge is a separate, explicit decision — never auto-merge from this skill\n","isInternal":false,"tokens":644,"sizeBytes":2481},{"name":"SKILL.md","path":".agents/skills/pr-push/SKILL.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.agents/skills/pr-push/SKILL.md","title":"pr-push","category":"anthropic-skill","format":"markdown","content":"---\nname: pr-push\ndescription: >-\n  Package the current working changes into a standards-compliant codex-proxy pull request:\n  branch hygiene, commit message linting, CHANGELOG prompt, conventional commit, push, and `gh pr create` against the `dev` branch.\n  TRIGGER when: user asks to \"push a PR\", \"open a PR\", \"create PR\", \"ship this\", \"推 PR\", \"开 PR\", \"提交 PR\".\n  DO NOT TRIGGER when: user only wants to commit without pushing; user explicitly wants to push directly to main; user wants to merge, rebase, or close an existing PR (use `gh pr merge` / `gh pr close` directly).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Edit\"\n  - \"Write\"\n  - \"Grep\"\n---\n\n# PR Push\n\nTurn the current working tree into a clean PR targeting `dev`. This skill enforces codex-proxy's contribution rules so community maintainers do not have to memorize them.\n\n## Overview\n\nCodex-proxy uses a `dev` → `main` promotion flow with strict commit conventions, CHANGELOG discipline, and a pre-push validation hook. This skill walks the maintainer through an interview, makes the commit, runs the push (letting the hook gate quality), and opens the PR. It explicitly stops before merge — review and merge are separate human decisions.\n\n## When to Use\n\n- A maintainer has finished a unit of work in their working tree and wants it on `dev`.\n- A maintainer asks to \"open a PR\" or equivalent and the working tree has changes (staged, unstaged, or untracked).\n\n## Important Rules\n\n1. **Target branch is always `dev`.** Never open a PR against `main` unless the user explicitly states \"target main\" with a written reason. The `main` branch is fast-forwarded by the `promote-dev-to-main.yml` workflow — manual PRs to `main` break that contract.\n2. **Never commit on `dev` or `main` directly.** If `git branch --show-current` is one of these, stop and ask the user to name a feature branch (`git switch -c <name>`).\n3. **Never use `git add -A`, `git add .`, or `git add -f`.** Stage files by explicit path. `-f` overrides `.gitignore` and has been the cause of secret leaks elsewhere.\n4. **Never pass `--no-verify` to `git commit` or `git push`.** The hook is the gate. If it fails, fix the underlying issue, do not bypass.\n5. **Stop after `gh pr create`.** Do not merge, do not approve, do not enable auto-merge. Pushing a PR and merging a PR are two human decisions.\n6. **CHANGELOG gate.** If any file under `src/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` changed, `CHANGELOG.md`'s `[Unreleased]` section MUST have a new entry covering the change before the commit is created.\n7. **Commit message format is fixed:** `<type>(<optional-scope>): <imperative summary>`. The type set is enumerated in `references/commit-conventions.md`.\n\n## Key Workflows\n\n### Phase 1: Discovery (interview, do not touch the repo yet)\n\n**Goal:** Understand what is being shipped before any git operation.\n\nRun these read-only commands in parallel and summarize results back to the user:\n\n```\ngit branch --show-current\ngit status --short\ngit diff --stat\ngit log --oneline -10\n```\n\nThen read the conventions:\n```\nRead: .Codex/skills/pr-push/references/commit-conventions.md\nRead: .Codex/skills/pr-push/references/changelog-format.md\nRead: .Codex/skills/pr-push/references/pr-checklist.md\n```\n\nAsk the user (in one consolidated message) for any field that cannot be inferred:\n\n- **Commit type** (feat / fix / refactor / docs / test / chore / perf / ci) — propose one based on the diff, ask for confirmation.\n- **One-line summary** (imperative, lowercase, no trailing period) — propose one based on the diff.\n- **PR target** — default `dev`. Confirm only if the user previously asked to deviate.\n- **CHANGELOG entry** — if the gate in Important Rules #6 applies and `CHANGELOG.md` `[Unreleased]` has no matching entry, ask the user to dictate one (or offer to draft one for review). Do not invent silently.\n- **Memory / docs touch** — if the change touches public protocol, request flow, auth lifecycle, or release infra, ask whether `AGENTS.md` needs updating in the same PR.\n\nDo **NOT** proceed to Phase 2 until the user has explicitly confirmed (a) commit type, (b) summary, (c) CHANGELOG status, (d) target = `dev`.\n\n### Phase 2: Branch hygiene\n\n**Goal:** Make sure the commit lands on a feature branch, not on `dev`/`main`.\n\n1. Check `git branch --show-current`.\n2. If the current branch is `dev` or `main`:\n   - Stop. Ask the user to provide a feature branch name (suggest one derived from the commit summary, kebab-case, ≤40 chars).\n   - Run `git switch -c <name>`. Do not auto-pick a name without confirmation.\n3. If the current branch is a feature branch but is not based on up-to-date `origin/dev`:\n   - Run `git fetch origin dev`.\n   - If `git merge-base --is-ancestor origin/dev HEAD` is false (branch is behind), warn the user and ask whether to `git rebase origin/dev` before continuing. Do not rebase silently.\n\n### Phase 3: Stage + commit\n\n**Goal:** Produce one well-formed commit.\n\n1. List the files the user wants in this commit. If they didn't say, propose the list from `git status --short` and confirm.\n2. Run `git add <file1> <file2> ...` with explicit paths. Never `-A`, `.`, or `-f`.\n3. If CHANGELOG was updated as part of Phase 1, include `CHANGELOG.md` in the staged set.\n4. Build the commit message:\n   - First line: `<type>(<scope>): <summary>` — scope is optional, omit parentheses if no scope.\n   - Body (optional): wrap at ~72 cols, explain *why*, reference issues with `Closes #N` / `Refs #N` if applicable.\n5. Commit with a HEREDOC (preserves formatting):\n   ```bash\n   git commit -m \"$(cat <<'EOF'\n   <type>(<scope>): <summary>\n\n   <optional body>\n   EOF\n   )\"\n   ```\n6. If the commit fails because of a pre-commit hook, fix the reported issue and create a NEW commit (do not `--amend`). Re-run the same command after fixes.\n\n### Phase 4: Push\n\n**Goal:** Get the branch to `origin` so a PR can be opened.\n\n1. Confirm the user wants to push (a single short \"ready to push?\" — they may have wanted to inspect the commit first).\n2. **Hook presence check.** The repo's pre-push gate lives at `.Codex/hooks/pre-push-validate.sh`, which is gitignored — fresh clones do **not** have it. Run `test -x .Codex/hooks/pre-push-validate.sh`:\n   - **Hook present** → push normally; the hook will run.\n   - **Hook missing** → warn the user that no pre-push gate is installed, then run the equivalent checks inline based on what the diff touched, before pushing:\n     | Diff touches | Run |\n     |---|---|\n     | `src/**` or `tests/**` | `npm test` and `npx tsc --noEmit` |\n     | `web/**` | `npm run build` |\n     | `Dockerfile`, `docker-compose*` | `docker build .` (or note user must verify) |\n     | `packages/electron/**`, `electron-builder.yml` | `npm run -w packages/electron build` |\n     | `native/**` | `npm run -w native build` |\n     Any failure aborts the push — fix and re-run.\n3. Run `git push -u origin HEAD`.\n4. If the push is blocked by the hook:\n   - Read the hook output verbatim back to the user.\n   - The hook validates the build targets affected by the diff (test, tsc, web build, Dockerfile lint, Electron config, native addon). Identify which target failed and propose a fix.\n   - **Never retry with `--no-verify`.** Re-run the offending check locally, fix the root cause, amend the commit only if the user authorizes it, otherwise add a fix-up commit.\n\n### Phase 5: Open the PR\n\n**Goal:** Create a PR against `dev` with a body that future reviewers can read cold.\n\n1. Read the PR body template:\n   ```\n   Read: .Codex/skills/pr-push/assets/pr-body-template.md\n   ```\n2. Determine PR title:\n   - If the branch has a single commit, reuse the commit subject.\n   - If multiple commits, propose a title that summarizes the branch's intent and confirm with user.\n   - Title MUST start with a conventional type, MUST be ≤72 chars.\n3. Fill the body sections (Summary / Test Plan / Notes). Source content from:\n   - `git log <base>..HEAD` for the change list.\n   - The CHANGELOG entry the user wrote.\n   - Test commands actually run locally (do not invent test results).\n4. Show the rendered title + body to the user. **Wait for explicit \"looks good\" before invoking `gh`.**\n5. Create the PR:\n   ```bash\n   gh pr create --base dev --title \"<title>\" --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n6. Print the PR URL.\n7. **STOP.** Do not run `gh pr merge`, `gh pr review --approve`, `gh pr edit --add-label`, or `--auto-merge` unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not assume the user wants every modified file in the PR — ask.\n- Do not auto-write the CHANGELOG entry without showing it for approval first.\n- Do not retry a failing pre-push hook with `--no-verify`.\n- Do not open the PR against `main` even if the user is on a branch named `main-fix-X` — branch name does not imply target.\n- Do not silently rebase. If the branch needs rebase against `origin/dev`, ask first.\n- Do not chain `gh pr create` with `gh pr merge`. Two separate decisions.\n","frontmatter":{"name":"pr-push","description":"Package the current working changes into a standards-compliant codex-proxy pull request: branch hygiene, commit message linting, CHANGELOG prompt, conventional commit, push, and `gh pr create` against the `dev` branch. TRIGGER when: user asks to \"push a PR\", \"open a PR\", \"create PR\", \"ship this\", \"推 PR\", \"开 PR\", \"提交 PR\". DO NOT TRIGGER when: user only wants to commit without pushing; user explicitly wants to push directly to main; user wants to merge, rebase, or close an existing PR (use `gh pr merge` / `gh pr close` directly).","allowed-tools":["Bash","Read","Edit","Write","Grep"],"allowedTools":["Bash","Read","Edit","Write","Grep"]},"allowedTools":["Bash","Read","Edit","Write","Grep"],"isInternal":false,"tokens":2335,"sizeBytes":9037},{"name":"bug-report.md","path":".claude/skills/issue-create/assets/bug-report.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.claude/skills/issue-create/assets/bug-report.md","title":"Assets Skill","category":"anthropic-skill","format":"markdown","content":"<!--\nBug report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nMatch the language of the repo's existing issues (currently a mix of zh-CN and en).\n-->\n\n## Summary\n\n{{One sentence describing the bug.}}\n\n## Expected behavior\n\n{{What the user thought would happen.}}\n\n## Actual behavior\n\n{{What actually happened.}}\n\n## Reproduction steps\n\n1. {{step 1}}\n2. {{step 2}}\n3. {{step 3 — describe the failure}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| Frequency | {{always / intermittent / once}} |\n| First broken version (if known) | {{version or \"unknown\"}} |\n| Workaround (if any) | {{description or \"none\"}} |\n\n## Logs / output\n\n```\n{{Paste relevant log lines. SECRETS REDACTED — no tokens, cookies,\noauth_state, API keys, account IDs.}}\n```\n\n## Additional context\n\n{{Anything else the maintainer should know. Remove this section if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n","isInternal":false,"tokens":291,"sizeBytes":1104},{"name":"feature-request.md","path":".claude/skills/issue-create/assets/feature-request.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.claude/skills/issue-create/assets/feature-request.md","title":"Assets Skill","category":"anthropic-skill","format":"markdown","content":"<!--\nFeature request template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\n-->\n\n## Summary\n\n{{One sentence describing the feature.}}\n\n## Problem\n\n{{The user-facing motivation. What can the user not do today, or what is\npainful about how they have to do it? DO NOT describe the proposed\nsolution here — only the problem.}}\n\n## Proposed solution\n\n{{High-level description of how the feature would work. Implementation\ndetail is welcome but not required. If you have a UI in mind, sketch\nor screenshot helps.}}\n\n## Alternatives considered\n\n{{Other approaches the user thought about and why they don't fit.\nEven \"I considered X but it doesn't work because Y\" is useful — it\nsaves the maintainer from re-deriving the same conclusion.}}\n\n## Who benefits\n\n{{single user / all users / a specific deployment mode (Electron / Docker / dev) /\na specific upstream provider / a specific account state}}\n\n## Impact if not done\n\n{{Does the user have a workaround? Is this blocking? Nice-to-have?\nRemove this section if \"no impact, just nice\".}}\n\n## Additional context\n\n{{Mockups, links, related discussions. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n","isInternal":false,"tokens":272,"sizeBytes":1205},{"name":"perf-report.md","path":".claude/skills/issue-create/assets/perf-report.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.claude/skills/issue-create/assets/perf-report.md","title":"Assets Skill","category":"anthropic-skill","format":"markdown","content":"<!--\nPerformance report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nA perf report without numbers is just a bug — switch to bug-report.md if\nno measurements are available.\n-->\n\n## Summary\n\n{{One sentence describing the regression or slowness.}}\n\n## Expected behavior\n\n{{What performance was expected, and where that expectation comes from\n(prior version, docs, comparable system).}}\n\n## Actual behavior\n\n{{What is observed instead.}}\n\n## Measurements\n\n| Metric | Baseline | Current | Delta |\n|---|---|---|---|\n| {{e.g. p95 latency}} | {{200ms}} | {{1.4s}} | {{+600%}} |\n| {{e.g. memory RSS}} | {{180MB}} | {{420MB}} | {{+133%}} |\n\n**Methodology:** {{How the numbers were taken — script, manual stopwatch,\nprofiler, load test. Be specific enough that a maintainer can reproduce.}}\n\n## Reproduction harness\n\n```\n{{Script, `tests/bench/...` reference, or numbered steps. Must be\ndeterministic enough to re-measure.}}\n```\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| First slow version (if known) | {{version or \"unknown\"}} |\n| Resource constraint hit | {{CPU / memory / network / FDs / \"none\"}} |\n\n## Logs / output\n\n```\n{{Relevant log lines or profiler output. SECRETS REDACTED.}}\n```\n\n## Additional context\n\n{{Anything else. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n","isInternal":false,"tokens":404,"sizeBytes":1508},{"name":"question.md","path":".claude/skills/issue-create/assets/question.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.claude/skills/issue-create/assets/question.md","title":"Assets Skill","category":"anthropic-skill","format":"markdown","content":"<!--\nQuestion template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nNote: if it turns out to be a bug, switch to the bug-report template.\n-->\n\n## What I'm trying to accomplish\n\n{{The end goal, not the immediate confusion. e.g. \"I want to route\ngpt-5.5 traffic only to my work account\" — not \"what does\nplan_mapping do?\"}}\n\n## What I tried\n\n{{Commands, config snippets, docs read, search terms used. Be specific.}}\n\n```yaml\n# Relevant config — SECRETS REDACTED\n{{config snippet or \"none\"}}\n```\n\n## What I expected\n\n{{What outcome did you anticipate?}}\n\n## What happened\n\n{{What did you actually observe?}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n\n## Additional context\n\n{{Logs, screenshots, anything else. Remove if empty.}}\n","isInternal":false,"tokens":243,"sizeBytes":909},{"name":"issue-types.md","path":".claude/skills/issue-create/references/issue-types.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.claude/skills/issue-create/references/issue-types.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Issue Type Specs\n\nRequired and optional fields per issue type. The skill enforces \"required\" — every required field must have either an answer or an explicit \"not applicable\" / \"unknown\" before the issue can be filed.\n\n## Bug\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Becomes part of the title; ≤72 chars |\n| Expected behavior | yes | What the user thought would happen |\n| Actual behavior | yes | What actually happened |\n| Reproduction steps | yes | Numbered list, deterministic |\n| Codex-proxy version | yes | `npm pkg get version` or About dialog |\n| Deployment mode | yes | Electron / Docker / `npm start` / dev / source |\n| OS + arch | yes | e.g. macOS 14.5 arm64, Windows 11 x64, Ubuntu 22.04 x64 |\n| Relevant logs | yes | Redact secrets; \"none\" is acceptable |\n| Frequency | yes | always / intermittent / once |\n| Workaround | no | If the user found one |\n| First broken version | no | If known (helps bisect) |\n| Related issues | no | `Refs #N` |\n\n## Feature Request\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Title material |\n| Problem statement | yes | The user-facing motivation. NOT the proposed solution. |\n| Proposed solution | yes | High level; implementation detail is welcome but optional |\n| Alternatives considered | yes | Even \"I considered X but it doesn't fit because Y\" |\n| Who benefits | yes | single user / all users / specific deployment mode / specific upstream |\n| Impact if NOT done | no | Does the user have a workaround? Is this blocking? |\n| Related issues / PRs | no | `Refs #N` |\n| Mockups / sketches | no | For UI features |\n\n## Question\n\n| Field | Required | Notes |\n|---|---|---|\n| What you're trying to accomplish | yes | The end goal, not the immediate confusion |\n| What you tried | yes | Commands, config, links to docs read |\n| What you expected | yes | |\n| What happened | yes | |\n| Relevant config | yes | Redact secrets; \"none\" if no config involved |\n| Codex-proxy version | yes | |\n| Deployment mode | yes | |\n\nIf a \"question\" turns out to be a bug during the interview, switch to the Bug template — do not file under `question`.\n\n## Performance\n\nAll Bug fields, plus:\n\n| Field | Required | Notes |\n|---|---|---|\n| Baseline measurement | yes | Numbers from a known-good version or expected baseline |\n| Current measurement | yes | Same metric, current version |\n| Measurement methodology | yes | How the numbers were taken — script, manual stopwatch, profiler |\n| Reproduction harness | yes | Script, `tests/bench/...` reference, or steps |\n| Resource constraint hit | no | CPU, memory, network, file descriptors, etc. |\n\nA perf report without numbers is a bug report — switch templates.\n\n## Documentation\n\n| Field | Required | Notes |\n|---|---|---|\n| Doc location | yes | File path (`README.md`, `CLAUDE.md`, `docs/...`) or URL |\n| What is wrong / missing | yes | Specific quote of the offending text, or \"this section is missing\" |\n| Suggested fix | no | Welcome but not required |\n| Audience affected | no | New users / operators / contributors / API consumers |\n","isInternal":false,"tokens":750,"sizeBytes":3083},{"name":"labels.md","path":".claude/skills/issue-create/references/labels.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.claude/skills/issue-create/references/labels.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Issue Labels (codex-proxy)\n\nThe complete catalog of labels currently defined on the repo. Apply only labels from this list — do not invent new ones. To propose a new label, file a `chore:` issue separately.\n\n| Label | Color | Use for |\n|---|---|---|\n| `bug` | #d73a4a | Something isn't working as documented or intended |\n| `enhancement` | #a2eeef | New feature or extension of an existing feature |\n| `documentation` | #0075ca | Improvements or additions to documentation |\n| `question` | #d876e3 | Further information is requested; not yet known to be a bug |\n| `help wanted` | #008672 | Maintainers welcome contributors to take this on |\n| `good first issue` | #7057ff | Small scope, low context required, friendly to newcomers |\n| `duplicate` | #cfd3d7 | Already filed elsewhere — set after triage, not on creation |\n| `invalid` | #e4e669 | Not actionable or out of scope — set after triage |\n| `wontfix` | #ffffff | Acknowledged but will not be addressed — set after triage |\n| `sync-conflict` | #d73a4a | `master → electron` auto-sync merge conflict — used by automation, not for human-filed issues |\n\n## Application rules for the skill\n\n1. **One type label minimum**: bug / enhancement / documentation / question (pick exactly one based on the issue type).\n2. **`good first issue`**: only when the user explicitly confirms the scope is small AND the fix is local (single file or single module).\n3. **`help wanted`**: when the reporter has no plan to send a PR themselves.\n4. **`documentation`** can be combined with `bug` or `enhancement` if the change requires both code and doc updates.\n5. **Never apply on creation**: `duplicate`, `invalid`, `wontfix`, `sync-conflict`. These are triage / automation labels.\n\n## CLI form\n\n```bash\ngh issue create --label \"bug,help wanted\" ...\n```\n\nMultiple labels are comma-separated (no space after the comma).\n","isInternal":false,"tokens":471,"sizeBytes":1869},{"name":"SKILL.md","path":".claude/skills/issue-create/SKILL.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.claude/skills/issue-create/SKILL.md","title":"issue-create","category":"anthropic-skill","format":"markdown","content":"---\nname: issue-create\ndescription: >-\n  Interview the user to gather all required context, then open a high-quality GitHub issue (`gh issue create`) on the codex-proxy repo with the right template, labels, and structured body.\n  TRIGGER when: user says \"open an issue\", \"file an issue\", \"create issue\", \"report a bug\", \"feature request\", \"提个 issue\", \"报 bug\", \"提需求\".\n  DO NOT TRIGGER when: user wants to view, search, comment on, or close existing issues (use `gh issue list/view/comment/close` directly); user is writing a PR description (use `pr-push`).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Write\"\n---\n\n# Issue Create\n\nGather complete context through a structured interview, then file a well-formed issue. The interview is a hard gate — vague issues waste maintainer time.\n\n## Overview\n\nMost \"I have a bug\" or \"I want a feature\" reports are missing the information a maintainer needs to act. This skill runs a four-phase interview, fills the appropriate template, applies the right labels, and only then calls `gh issue create`. The user sees and approves the rendered body before submission.\n\n## When to Use\n\n- A user wants to file a new issue on the codex-proxy repository.\n- A user describes a bug or feature in conversation and asks \"should we file an issue?\"\n\n## Important Rules\n\n1. **The interview is not optional.** Do NOT call `gh issue create` until all required fields for the chosen type are collected and the user has explicitly approved the rendered body.\n2. **Never invent reproduction steps, version numbers, log output, or behavior.** If the user did not provide it, ask. If they cannot provide it, write \"not provided\" in the field, do not fabricate.\n3. **Show the full body before submitting.** The user must explicitly say \"submit\" / \"looks good\" / equivalent. \"Yes\" without seeing the body is not enough — show it first.\n4. **Apply only labels from the project's existing label set.** Read `references/labels.md` for the catalog. Do not invent new labels.\n5. **Strip secrets.** If the user pastes logs, headers, or config that contain tokens, cookies, OAuth state, API keys, or account IDs, redact them before they enter the issue body. Replace with `<redacted>`.\n6. **One issue per scope.** If the user describes two unrelated problems, file two issues. Ask before splitting.\n\n## Key Workflows\n\n### Phase 1: Type classification\n\n**Goal:** Pick the right template and label.\n\nAsk the user (one consolidated question):\n\n> What type of issue is this?\n>   1. **Bug** — something is broken or behaves incorrectly\n>   2. **Feature request** — propose new functionality\n>   3. **Question** — usage / configuration / \"is this expected?\"\n>   4. **Performance** — measurable regression or slowness\n>   5. **Documentation** — docs are wrong, missing, or unclear\n\nRead the type spec:\n```\nRead: .claude/skills/issue-create/references/issue-types.md\n```\n\nMap answer to template path:\n\n| Type | Template asset | Default label |\n|---|---|---|\n| Bug | `assets/bug-report.md` | `bug` |\n| Feature request | `assets/feature-request.md` | `enhancement` |\n| Question | `assets/question.md` | `question` |\n| Performance | `assets/perf-report.md` | `bug` |\n| Documentation | `assets/feature-request.md` (with docs framing) | `documentation` |\n\nDo **NOT** proceed to Phase 2 until the type is confirmed.\n\n### Phase 2: Required-field interview\n\n**Goal:** Collect every field the chosen template requires.\n\nRead `references/issue-types.md` to see the required-field table for the chosen type. Ask for missing fields in **one consolidated message**, not one at a time. Group related fields together.\n\n**For bugs**, the required fields are:\n- One-line summary\n- Expected behavior\n- Actual behavior\n- Reproduction steps (numbered)\n- Codex-proxy version (`npm pkg get version` or app About dialog)\n- Deployment mode (Electron app / Docker / `npm start` / dev)\n- Relevant log lines (redact secrets)\n- Frequency (always / intermittent / once)\n\n**For feature requests**, the required fields are:\n- Problem the feature solves (user-facing motivation, not the proposed solution)\n- Proposed solution (high level)\n- Alternatives considered\n- Who benefits (single user / all users / specific deployment mode)\n\n**For questions**:\n- What you tried\n- What you expected\n- What happened\n- Relevant config (redact secrets)\n\n**For performance**:\n- All bug fields, plus:\n- Measured baseline vs current (timings, memory, request count — be specific)\n- Reproduction harness (script, steps, or `tests/bench/`)\n\n**For documentation**:\n- Which doc page / file\n- What is wrong or missing\n- Suggested fix (if any)\n\nIf a field cannot be answered, the user must explicitly say \"not applicable\" or \"unknown\" — record that verbatim. Do not silently skip.\n\nDo **NOT** proceed to Phase 3 until every required field has either an answer or an explicit \"not applicable\".\n\n### Phase 3: Code & related-context grounding\n\n**Goal:** Help maintainers find the relevant code fast.\n\nAsk the user for:\n- File paths or `file:line` references they suspect are involved (optional but encouraged).\n- Related issues / PRs to link (`Refs #N`, `Related to #N`).\n- Whether they tried searching existing issues (`gh issue list --search \"<keywords>\"`). If they have not and the report sounds like something that might exist, run the search and show top 3 matches before continuing.\n\nIf the user provides no code locations and the bug is concrete, optionally offer:\n> \"Want me to grep for the relevant code so we can include file:line in the issue?\"\n\nDo not grep silently — ask first, and only do it once.\n\n### Phase 4: Render, confirm, submit\n\n**Goal:** Show the final body, get explicit approval, file the issue.\n\n1. Read the chosen template:\n   ```\n   Read: .claude/skills/issue-create/assets/<template>.md\n   ```\n2. Read the labels catalog:\n   ```\n   Read: .claude/skills/issue-create/references/labels.md\n   ```\n3. Fill the template with the collected fields. Strip secrets per Important Rule #5.\n4. Pick labels:\n   - Always include the type label (Phase 1 mapping).\n   - Add `good first issue` only if the user explicitly says it qualifies (small scope, low context required).\n   - Add `help wanted` if the user has no plan to fix it themselves.\n   - Add `documentation` in addition to the type label if docs need updating.\n5. Show the user the complete rendered output:\n   ```\n   Title: <title>\n   Labels: <label1>, <label2>\n   Body:\n   <full body>\n   ```\n6. Ask: \"Ready to submit, or want to adjust anything?\"\n7. Wait for an explicit affirmative. \"Yes\", \"submit\", \"go\", \"looks good\", \"提交\" all qualify. Silence or hedging does not.\n8. Submit:\n   ```bash\n   gh issue create \\\n     --title \"<title>\" \\\n     --label \"<label1>,<label2>\" \\\n     --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n9. Print the issue URL.\n10. **STOP.** Do not assign, do not comment, do not link to projects unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not call `gh issue create` before showing the body for approval.\n- Do not invent reproduction steps when the user gave a vague report — ask.\n- Do not paste raw logs that contain tokens / cookies / OAuth state / account IDs.\n- Do not apply labels outside the existing catalog.\n- Do not file two issues from one report without confirming the split with the user.\n- Do not grep / search the codebase silently to \"fill in\" missing fields — ask first.\n","frontmatter":{"name":"issue-create","description":"Interview the user to gather all required context, then open a high-quality GitHub issue (`gh issue create`) on the codex-proxy repo with the right template, labels, and structured body. TRIGGER when: user says \"open an issue\", \"file an issue\", \"create issue\", \"report a bug\", \"feature request\", \"提个 issue\", \"报 bug\", \"提需求\". DO NOT TRIGGER when: user wants to view, search, comment on, or close existing issues (use `gh issue list/view/comment/close` directly); user is writing a PR description (use `pr-push`).","allowed-tools":["Bash","Read","Write"],"allowedTools":["Bash","Read","Write"]},"allowedTools":["Bash","Read","Write"],"isInternal":false,"tokens":1771,"sizeBytes":7405},{"name":"pr-body-template.md","path":".claude/skills/pr-push/assets/pr-body-template.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.claude/skills/pr-push/assets/pr-body-template.md","title":"Assets Skill","category":"anthropic-skill","format":"markdown","content":"<!--\nPR body template for codex-proxy. The skill fills in the {{placeholders}}\nand removes optional sections that don't apply. Default language follows\nthe repo's dominant language (currently zh-CN for CHANGELOG entries,\nen for code/commits). Pick one and stay consistent within a single PR.\n-->\n\n## Summary\n\n{{One paragraph: WHAT changed and WHY. Reference the user-visible impact.\nIf multiple commits, summarize the branch's intent, not each commit.}}\n\n## Changes\n\n{{Bulleted list mirroring the CHANGELOG entry. Group by area when the PR\ntouches multiple modules. Reference file paths so reviewers can navigate.}}\n\n- {{change 1 — files}}\n- {{change 2 — files}}\n\n## Test Plan\n\n{{List the commands actually run locally. Do not invent results.\nMark checked items with [x], unchecked with [ ].}}\n\n- [ ] `npm test`\n- [ ] `npm run build`\n- [ ] {{any feature-specific manual verification, e.g. \"Verified Dashboard 用量页 cache hit card renders with mock data\"}}\n- [ ] {{`npm run test:real` if the change touches upstream protocol}}\n\n## Notes\n\n{{Optional. Use for any of:\n - Reviewer attention requests (\"please double-check the SSE buffer math in src/...\")\n - Known follow-ups (\"memory entry for new RT format will land in a separate PR\")\n - Migration / config impact (\"operators must add `update.allow_prerelease` if they want beta\")\n - Screenshots for UI changes\nRemove this section if there are no notes.}}\n\n## Linked Issues\n\n{{Closes #N / Refs #N — remove if none.}}\n","isInternal":false,"tokens":340,"sizeBytes":1475},{"name":"changelog-format.md","path":".claude/skills/pr-push/references/changelog-format.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.claude/skills/pr-push/references/changelog-format.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# CHANGELOG Format\n\nCodex-proxy follows [Keep a Changelog](https://keepachangelog.com/). Every PR that changes user-visible behavior, public API, configuration, or build/release infrastructure MUST add an entry to `CHANGELOG.md` under `## [Unreleased]`.\n\n## Section Layout\n\n`## [Unreleased]` contains exactly these subsections (in this order, omit empty ones):\n\n```markdown\n## [Unreleased]\n\n### Changed\n\n- ...\n\n### Added\n\n- ...\n\n### Fixed\n\n- ...\n```\n\n| Subsection | Use for |\n|---|---|\n| `### Added` | New features, new endpoints, new config keys, new CLI flags |\n| `### Changed` | Behavior change of existing features, default value changes, signature changes |\n| `### Fixed` | Bug fixes |\n| `### Removed` | Deleted features (rare; gate behind a deprecation cycle first) |\n| `### Deprecated` | Marking something for future removal |\n| `### Security` | Security-relevant fix (CVE, cred leak, etc.) |\n\n## Entry Style\n\n- Use the same language as the existing `[Unreleased]` entries (zh-CN at time of writing). If the file flips to English, follow.\n- Lead with the user-visible impact, then mention the file paths in parentheses for reviewer navigation.\n- Reference issues / PRs with `(#NNN)` inline.\n- Multi-aspect entries get nested bullets.\n\n## Examples (from current `[Unreleased]`)\n\n```markdown\n### Added\n\n- 图像生成请求计数（成功 / 失败分流）：`AccountUsage` 新增 `image_request_count` / `image_request_failed_count`...\n- Dashboard 用量统计新增「缓存命中率」卡片...\n```\n\n```markdown\n### Changed\n\n- `bump-electron-beta.yml` 触发改为定时 cron（每天 04:00 / 12:00 UTC）...\n```\n\n## When NOT to add a CHANGELOG entry\n\nSkip CHANGELOG for commits that are:\n\n- Test-only (`test:` prefix) — no user impact\n- Doc-only edits to internal docs (`CLAUDE.md`, `.claude/`, `docs/dev-notes/`)\n- Pure refactors that change zero observed behavior (`refactor:` prefix with no API surface change)\n- CI-only changes that do not affect built artifacts (`ci:` prefix)\n- Style/formatting (`style:` prefix)\n\nIf unsure, **add the entry**. A redundant entry is cheaper than a missing one.\n\n## Multi-line / multi-bullet entries\n\nUse the existing nested bullet pattern:\n\n```markdown\n- Ollama bridge cleanup (#403 review followups, closes #405 #406 #407):\n  - `src/ollama/bridge.ts` 不再重复实现 `normalizeHostname`...\n  - `proxyOpenAIRequest` 转发头扩展到...\n  - `MAX_SSE_BUFFER` 重命名为 `MAX_SSE_BUFFER_CHARS`...\n```\n","isInternal":false,"tokens":633,"sizeBytes":2454},{"name":"commit-conventions.md","path":".claude/skills/pr-push/references/commit-conventions.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.claude/skills/pr-push/references/commit-conventions.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Commit Message Conventions\n\nCodex-proxy uses Conventional Commits with a fixed type vocabulary. Several CI workflows pattern-match on the type prefix, so unknown types break automation.\n\n## Format\n\n```\n<type>(<optional scope>): <imperative summary>\n\n<optional body — wrap at ~72 cols, explain WHY>\n\n<optional footer — Closes #N, Refs #N, BREAKING CHANGE: ...>\n```\n\n- Subject is **imperative mood**, lowercase first letter, no trailing period.\n- Subject ≤ 72 chars hard cap.\n- Body explains *why* the change was made, not *what* (the diff shows what).\n\n## Type Vocabulary\n\n| Type | Use for | Triggers beta release? |\n|---|---|---|\n| `feat` | New user-visible feature | yes |\n| `fix` | Bug fix | yes |\n| `perf` | Performance improvement with no behavior change | yes |\n| `refactor` | Code restructuring with no behavior change | no |\n| `docs` | Documentation only | no |\n| `test` | Test-only changes | no |\n| `chore` | Tooling, dependencies, repo housekeeping | no |\n| `ci` | CI/CD configuration | no |\n| `style` | Formatting, whitespace, no logic change | no |\n\nThe \"Triggers beta release?\" column is determined by `bump-electron-beta.yml`'s skip filter: `^(chore|docs|ci|test|refactor|style)`. Note that `fix(ci):` still triggers a beta release because the prefix is `fix`.\n\n## Scope\n\nOptional, but encouraged for clarity. Use the top-level module name:\n\n- `feat(auth): ...`\n- `fix(translation): ...`\n- `refactor(routes): ...`\n- `chore(deps): ...`\n- `ci(release): ...`\n\nSkip the scope when the change spans multiple modules or is genuinely repo-wide.\n\n## Examples\n\nGood:\n\n```\nfeat(auth): persist account-pool RT-only imports across restarts\n```\n\n```\nfix(translation): recover from previous_response_not_found instead of passing it through\n```\n\n```\nrefactor(routes): extract shared proxy-handler from openai/anthropic/gemini handlers\n```\n\nBad — and why:\n\n| Message | Why it fails |\n|---|---|\n| `Update auth.ts` | No type, describes WHAT not WHY |\n| `feat: Added new feature.` | Past tense + capitalized + trailing period |\n| `feature(auth): persist RT` | `feature` is not in the vocabulary, use `feat` |\n| `fix: stuff` | Subject is meaningless |\n| `wip` | No type, no information |\n\n## Multi-line body\n\nUse a HEREDOC to preserve formatting:\n\n```bash\ngit commit -m \"$(cat <<'EOF'\nfix(quota): ignore stale x-codex-* headers after token refresh\n\nThe previous behavior overwrote fresh quota state with cached headers\nfrom the old token, causing accounts to appear over-quota for ~30s\nafter refresh. Now we drop quota updates whose token id does not match\nthe current session.\n\nCloses #418\nEOF\n)\"\n```\n","isInternal":false,"tokens":670,"sizeBytes":2605},{"name":"pr-checklist.md","path":".claude/skills/pr-push/references/pr-checklist.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.claude/skills/pr-push/references/pr-checklist.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# Pre-PR Self-Check\n\nWalk this list before opening the PR. Anything left unchecked needs a written reason in the PR body.\n\n## Branch & target\n\n- [ ] Current branch is NOT `dev`, `master`, or `main`\n- [ ] Branch is rebased on (or fast-forwardable to) `origin/dev`\n- [ ] PR target = `dev`\n\n## Commit hygiene\n\n- [ ] Each commit follows `<type>(<scope>): <summary>` with a vocabulary type (see `commit-conventions.md`)\n- [ ] No commit was created with `--no-verify`\n- [ ] No file added with `git add -f`\n- [ ] No accidental staging of `node_modules/`, `dist/`, `*.log`, `.env*`, `data/`, or other gitignored paths\n- [ ] No secrets in code or commit messages (API keys, tokens, cookies, oauth_state)\n\n## CHANGELOG\n\n- [ ] If the change touches `src/`, `shared/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` → `CHANGELOG.md` `[Unreleased]` has a new entry\n- [ ] Entry placed in correct subsection (Added / Changed / Fixed)\n- [ ] Entry references the issue / PR number when applicable\n\n## Cross-artifact impact\n\nCodex-proxy ships three artifacts: backend (Docker), Electron desktop, web frontend. The pre-push hook will catch most of these, but verify mentally first:\n\n- [ ] If `src/` changed → backend logic still passes `npm test`\n- [ ] If `web/` changed → `npm run build` produces a clean Vite bundle\n- [ ] If `Dockerfile` / `docker-compose*` changed → image still builds\n- [ ] If `packages/electron/**` or `electron-builder.yml` changed → Electron config validates\n- [ ] If `native/**` changed → native addon still builds\n\n## Tests\n\n- [ ] New behavior has new tests (TDD: tests written first when feasible)\n- [ ] All affected `npm test` suites pass locally\n- [ ] No `*.skip` left behind unless explicitly justified in the PR body\n\n## TypeScript\n\n- [ ] No `any`, `as any`, `: any`, or `<any>` in new code (use `unknown`, generics, or specific types)\n- [ ] No `@ts-ignore` / `@ts-expect-error` without an inline explanation comment\n\n## Real-upstream changes\n\n- [ ] If the change touches the upstream protocol (translation/, proxy/, auth/), `npm run test:real` was attempted at least once\n\n## Documentation\n\n- [ ] Public-facing config/flag changes are reflected in `config/default.yaml` comments and `CLAUDE.md` if relevant\n- [ ] No internal personal notes leaked into committed files\n\n## After push (do NOT do these in this skill)\n\n- [ ] Wait for CI green before requesting review\n- [ ] Merge is a separate, explicit decision — never auto-merge from this skill\n","isInternal":false,"tokens":647,"sizeBytes":2492},{"name":"SKILL.md","path":".claude/skills/pr-push/SKILL.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/.claude/skills/pr-push/SKILL.md","title":"pr-push","category":"anthropic-skill","format":"markdown","content":"---\nname: pr-push\ndescription: >-\n  Package the current working changes into a standards-compliant codex-proxy pull request:\n  branch hygiene, commit message linting, CHANGELOG prompt, conventional commit, push, and `gh pr create` against the `dev` branch.\n  TRIGGER when: user asks to \"push a PR\", \"open a PR\", \"create PR\", \"ship this\", \"推 PR\", \"开 PR\", \"提交 PR\".\n  DO NOT TRIGGER when: user only wants to commit without pushing; user explicitly wants to push directly to master/main; user wants to merge, rebase, or close an existing PR (use `gh pr merge` / `gh pr close` directly).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Edit\"\n  - \"Write\"\n  - \"Grep\"\n---\n\n# PR Push\n\nTurn the current working tree into a clean PR targeting `dev`. This skill enforces codex-proxy's contribution rules so community maintainers do not have to memorize them.\n\n## Overview\n\nCodex-proxy uses a `dev` → `master` promotion flow with strict commit conventions, CHANGELOG discipline, and a pre-push validation hook. This skill walks the maintainer through an interview, makes the commit, runs the push (letting the hook gate quality), and opens the PR. It explicitly stops before merge — review and merge are separate human decisions.\n\n## When to Use\n\n- A maintainer has finished a unit of work in their working tree and wants it on `dev`.\n- A maintainer asks to \"open a PR\" or equivalent and the working tree has changes (staged, unstaged, or untracked).\n\n## Important Rules\n\n1. **Target branch is always `dev`.** Never open a PR against `master` or `main` unless the user explicitly states \"target master\" with a written reason. The `master` branch is fast-forwarded by the `promote-dev-to-master.yml` workflow — manual PRs to `master` break that contract.\n2. **Never commit on `dev`, `master`, or `main` directly.** If `git branch --show-current` is one of these, stop and ask the user to name a feature branch (`git switch -c <name>`).\n3. **Never use `git add -A`, `git add .`, or `git add -f`.** Stage files by explicit path. `-f` overrides `.gitignore` and has been the cause of secret leaks elsewhere.\n4. **Never pass `--no-verify` to `git commit` or `git push`.** The hook is the gate. If it fails, fix the underlying issue, do not bypass.\n5. **Stop after `gh pr create`.** Do not merge, do not approve, do not enable auto-merge. Pushing a PR and merging a PR are two human decisions.\n6. **CHANGELOG gate.** If any file under `src/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` changed, `CHANGELOG.md`'s `[Unreleased]` section MUST have a new entry covering the change before the commit is created.\n7. **Commit message format is fixed:** `<type>(<optional-scope>): <imperative summary>`. The type set is enumerated in `references/commit-conventions.md`.\n\n## Key Workflows\n\n### Phase 1: Discovery (interview, do not touch the repo yet)\n\n**Goal:** Understand what is being shipped before any git operation.\n\nRun these read-only commands in parallel and summarize results back to the user:\n\n```\ngit branch --show-current\ngit status --short\ngit diff --stat\ngit log --oneline -10\n```\n\nThen read the conventions:\n```\nRead: .claude/skills/pr-push/references/commit-conventions.md\nRead: .claude/skills/pr-push/references/changelog-format.md\nRead: .claude/skills/pr-push/references/pr-checklist.md\n```\n\nAsk the user (in one consolidated message) for any field that cannot be inferred:\n\n- **Commit type** (feat / fix / refactor / docs / test / chore / perf / ci) — propose one based on the diff, ask for confirmation.\n- **One-line summary** (imperative, lowercase, no trailing period) — propose one based on the diff.\n- **PR target** — default `dev`. Confirm only if the user previously asked to deviate.\n- **CHANGELOG entry** — if the gate in Important Rules #6 applies and `CHANGELOG.md` `[Unreleased]` has no matching entry, ask the user to dictate one (or offer to draft one for review). Do not invent silently.\n- **Memory / docs touch** — if the change touches public protocol, request flow, auth lifecycle, or release infra, ask whether `CLAUDE.md` needs updating in the same PR.\n\nDo **NOT** proceed to Phase 2 until the user has explicitly confirmed (a) commit type, (b) summary, (c) CHANGELOG status, (d) target = `dev`.\n\n### Phase 2: Branch hygiene\n\n**Goal:** Make sure the commit lands on a feature branch, not on `dev`/`master`.\n\n1. Check `git branch --show-current`.\n2. If the current branch is `dev`, `master`, or `main`:\n   - Stop. Ask the user to provide a feature branch name (suggest one derived from the commit summary, kebab-case, ≤40 chars).\n   - Run `git switch -c <name>`. Do not auto-pick a name without confirmation.\n3. If the current branch is a feature branch but is not based on up-to-date `origin/dev`:\n   - Run `git fetch origin dev`.\n   - If `git merge-base --is-ancestor origin/dev HEAD` is false (branch is behind), warn the user and ask whether to `git rebase origin/dev` before continuing. Do not rebase silently.\n\n### Phase 3: Stage + commit\n\n**Goal:** Produce one well-formed commit.\n\n1. List the files the user wants in this commit. If they didn't say, propose the list from `git status --short` and confirm.\n2. Run `git add <file1> <file2> ...` with explicit paths. Never `-A`, `.`, or `-f`.\n3. If CHANGELOG was updated as part of Phase 1, include `CHANGELOG.md` in the staged set.\n4. Build the commit message:\n   - First line: `<type>(<scope>): <summary>` — scope is optional, omit parentheses if no scope.\n   - Body (optional): wrap at ~72 cols, explain *why*, reference issues with `Closes #N` / `Refs #N` if applicable.\n5. Commit with a HEREDOC (preserves formatting):\n   ```bash\n   git commit -m \"$(cat <<'EOF'\n   <type>(<scope>): <summary>\n\n   <optional body>\n   EOF\n   )\"\n   ```\n6. If the commit fails because of a pre-commit hook, fix the reported issue and create a NEW commit (do not `--amend`). Re-run the same command after fixes.\n\n### Phase 4: Push\n\n**Goal:** Get the branch to `origin` so a PR can be opened.\n\n1. Confirm the user wants to push (a single short \"ready to push?\" — they may have wanted to inspect the commit first).\n2. **Hook presence check.** The repo's pre-push gate lives at `.claude/hooks/pre-push-validate.sh`, which is gitignored — fresh clones do **not** have it. Run `test -x .claude/hooks/pre-push-validate.sh`:\n   - **Hook present** → push normally; the hook will run.\n   - **Hook missing** → warn the user that no pre-push gate is installed, then run the equivalent checks inline based on what the diff touched, before pushing:\n     | Diff touches | Run |\n     |---|---|\n     | `src/**` or `tests/**` | `npm test` and `npx tsc --noEmit` |\n     | `web/**` | `npm run build` |\n     | `Dockerfile`, `docker-compose*` | `docker build .` (or note user must verify) |\n     | `packages/electron/**`, `electron-builder.yml` | `npm run -w packages/electron build` |\n     | `native/**` | `npm run -w native build` |\n     Any failure aborts the push — fix and re-run.\n3. Run `git push -u origin HEAD`.\n4. If the push is blocked by the hook:\n   - Read the hook output verbatim back to the user.\n   - The hook validates the build targets affected by the diff (test, tsc, web build, Dockerfile lint, Electron config, native addon). Identify which target failed and propose a fix.\n   - **Never retry with `--no-verify`.** Re-run the offending check locally, fix the root cause, amend the commit only if the user authorizes it, otherwise add a fix-up commit.\n\n### Phase 5: Open the PR\n\n**Goal:** Create a PR against `dev` with a body that future reviewers can read cold.\n\n1. Read the PR body template:\n   ```\n   Read: .claude/skills/pr-push/assets/pr-body-template.md\n   ```\n2. Determine PR title:\n   - If the branch has a single commit, reuse the commit subject.\n   - If multiple commits, propose a title that summarizes the branch's intent and confirm with user.\n   - Title MUST start with a conventional type, MUST be ≤72 chars.\n3. Fill the body sections (Summary / Test Plan / Notes). Source content from:\n   - `git log <base>..HEAD` for the change list.\n   - The CHANGELOG entry the user wrote.\n   - Test commands actually run locally (do not invent test results).\n4. Show the rendered title + body to the user. **Wait for explicit \"looks good\" before invoking `gh`.**\n5. Create the PR:\n   ```bash\n   gh pr create --base dev --title \"<title>\" --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n6. Print the PR URL.\n7. **STOP.** Do not run `gh pr merge`, `gh pr review --approve`, `gh pr edit --add-label`, or `--auto-merge` unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not assume the user wants every modified file in the PR — ask.\n- Do not auto-write the CHANGELOG entry without showing it for approval first.\n- Do not retry a failing pre-push hook with `--no-verify`.\n- Do not open the PR against `master` even if the user is on a branch named `master-fix-X` — branch name does not imply target.\n- Do not silently rebase. If the branch needs rebase against `origin/dev`, ask first.\n- Do not chain `gh pr create` with `gh pr merge`. Two separate decisions.\n","frontmatter":{"name":"pr-push","description":"Package the current working changes into a standards-compliant codex-proxy pull request: branch hygiene, commit message linting, CHANGELOG prompt, conventional commit, push, and `gh pr create` against the `dev` branch. TRIGGER when: user asks to \"push a PR\", \"open a PR\", \"create PR\", \"ship this\", \"推 PR\", \"开 PR\", \"提交 PR\". DO NOT TRIGGER when: user only wants to commit without pushing; user explicitly wants to push directly to master/main; user wants to merge, rebase, or close an existing PR (use `gh pr merge` / `gh pr close` directly).","allowed-tools":["Bash","Read","Edit","Write","Grep"],"allowedTools":["Bash","Read","Edit","Write","Grep"]},"allowedTools":["Bash","Read","Edit","Write","Grep"],"isInternal":false,"tokens":2347,"sizeBytes":9100},{"name":"README.md","path":"packages/npm/README.md","rawUrl":"https://raw.githubusercontent.com/icebear0828/codex-proxy/HEAD/packages/npm/README.md","title":"npm Documentation","category":"plugin-manifest","format":"markdown","content":"# @icebear0828/codex-proxy\n\nOpenAI-compatible proxy for the ChatGPT Codex Responses API, with a web dashboard, a multi-account key pool and an Ollama-compatible bridge. This is the full application — dashboard, account management and the Ollama bridge all work the same as the desktop and Docker versions.\n\n## Install\n\nRequires Node.js 22.13+ (uses the built-in `node:sqlite`).\n\nThis package is published to GitHub Packages, not to the public npmjs registry. Installing it from GitHub Packages needs an npm auth token with `read:packages`:\n\n```ini\n@icebear0828:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\n```\n\n```bash\nnpm install -g @icebear0828/codex-proxy\n```\n\nNo-auth alternative: download `codex-proxy-npm.zip` from the [latest release](https://github.com/icebear0828/codex-proxy/releases/latest/download/codex-proxy-npm.zip), extract it and run `node install.mjs` inside the extracted directory.\n\n## Run\n\n```bash\ncodex-proxy            # starts the server and opens the dashboard\ncodex-proxy --mode=server   # headless server only\ncodex-proxy --mode=browser  # force the system browser\ncodex-proxy --help          # all options\n```\n\nOn first start the dashboard opens at `http://127.0.0.1:8080` (port configurable via `--port` or `PORT`). On Windows the dashboard opens in your system browser; the desktop app and the Lite zip ship a native WebView2 host, which the npm package does not include.\n\nRuntime data (accounts, config, usage history) is stored in the per-user data directory (`%APPDATA%\\@codex-proxy\\electron\\data` on Windows, `~/.config/@codex-proxy/electron/data` on Linux, `~/Library/Application Support/@codex-proxy/electron/data` on macOS), so it survives package updates. Set `CODEX_PROXY_DATA_DIR` or pass `--portable` to relocate it. Platform-specific TLS addons are installed automatically for your OS/architecture; binaries for other platforms are never downloaded.\n\n## Links\n\n- [GitHub repository](https://github.com/icebear0828/codex-proxy)\n- [Documentation & screenshots](https://github.com/icebear0828/codex-proxy#readme)\n- Desktop installers, the portable zip and Docker images are published on the [releases page](https://github.com/icebear0828/codex-proxy/releases).\n\n## License\n\nNon-commercial licence — see [LICENCE](https://github.com/icebear0828/codex-proxy/blob/dev/LICENCE).\n","isInternal":false,"tokens":584,"sizeBytes":2367}],"systemPromptSnippet":"<yakaai_skills repo=\"icebear0828/codex-proxy\">\n<!-- File: AGENTS.md (Tokens: ~576 | Category: root-instruction) -->\n## 多 Agent 工作流\n\n- 仅在用户明确授权或任务明确要求时启用；完整规则见 `docs/MULTI_AGENT_WORKFLOW.md`。\n- 默认在满足最低安全和验收要求的前提下，优先减少总 token、credits、费用与重复阅读。\n- 开工前按语义难度、修改范围、可验证性、失败后果和上下文负担预分类。\n- 使用预计可完成任务的最低成本执行体；高性能执行体只用于关键推理、弱机械验收或高后果节点。\n- 简单任务不为使用多 Agent 增加调度成本；并行优先用于互不重叠的只读工作。\n- 同一工作树和合同域保持单写者；Reviewer/Verifier 默认只读。\n- 子 Agent 使用最小上下文、稳定公共前缀与增量证据，避免完整历史复制和重复读取。\n- 多 Agent 授权不扩大网络、真实 API、外部写入、提交、发布或破坏性操作权限。\n- 达到当前任务验收或停止条件后立即停止，不自动进入下一票据。\n\n## Gemini / Antigravity Schema 与日志\n\n- Gemini / Antigravity 的工具参数及结构化输出 schema 必须按 Gemini 支持的字段白名单清洗；清除 `prefixItems` 等不支持字段后，如果 schema 仍为 `type: array` 且缺少 `items`，需补宽松的 `{}` schema，避免 Gemini 的 `missing field` 校验错误。为此类变换补充嵌套 schema 回归测试。\n- 持久化请求/错误诊断时，必须先脱敏并限制单条记录和文件大小；不要提交临时的原始 tools / request dump，也不要记录凭据。\n\n## Keepalive safety\n\n- Account keepalive is disabled by default. Enabling the scheduler or calling `POST /admin/keepalive-run` sends real requests to `/codex/usage`; unit tests must mock `CodexApi`, and real-account execution requires explicit user authorization.\n\n<!-- File: .agents/skills/issue-create/assets/bug-report.md (Tokens: ~291 | Category: anthropic-skill) -->\n<!--\nBug report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nMatch the language of the repo's existing issues (currently a mix of zh-CN and en).\n-->\n\n## Summary\n\n{{One sentence describing the bug.}}\n\n## Expected behavior\n\n{{What the user thought would happen.}}\n\n## Actual behavior\n\n{{What actually happened.}}\n\n## Reproduction steps\n\n1. {{step 1}}\n2. {{step 2}}\n3. {{step 3 — describe the failure}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| Frequency | {{always / intermittent / once}} |\n| First broken version (if known) | {{version or \"unknown\"}} |\n| Workaround (if any) | {{description or \"none\"}} |\n\n## Logs / output\n\n```\n{{Paste relevant log lines. SECRETS REDACTED — no tokens, cookies,\noauth_state, API keys, account IDs.}}\n```\n\n## Additional context\n\n{{Anything else the maintainer should know. Remove this section if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n\n<!-- File: .agents/skills/issue-create/assets/feature-request.md (Tokens: ~272 | Category: anthropic-skill) -->\n<!--\nFeature request template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\n-->\n\n## Summary\n\n{{One sentence describing the feature.}}\n\n## Problem\n\n{{The user-facing motivation. What can the user not do today, or what is\npainful about how they have to do it? DO NOT describe the proposed\nsolution here — only the problem.}}\n\n## Proposed solution\n\n{{High-level description of how the feature would work. Implementation\ndetail is welcome but not required. If you have a UI in mind, sketch\nor screenshot helps.}}\n\n## Alternatives considered\n\n{{Other approaches the user thought about and why they don't fit.\nEven \"I considered X but it doesn't work because Y\" is useful — it\nsaves the maintainer from re-deriving the same conclusion.}}\n\n## Who benefits\n\n{{single user / all users / a specific deployment mode (Electron / Docker / dev) /\na specific upstream provider / a specific account state}}\n\n## Impact if not done\n\n{{Does the user have a workaround? Is this blocking? Nice-to-have?\nRemove this section if \"no impact, just nice\".}}\n\n## Additional context\n\n{{Mockups, links, related discussions. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n\n<!-- File: .agents/skills/issue-create/assets/perf-report.md (Tokens: ~404 | Category: anthropic-skill) -->\n<!--\nPerformance report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nA perf report without numbers is just a bug — switch to bug-report.md if\nno measurements are available.\n-->\n\n## Summary\n\n{{One sentence describing the regression or slowness.}}\n\n## Expected behavior\n\n{{What performance was expected, and where that expectation comes from\n(prior version, docs, comparable system).}}\n\n## Actual behavior\n\n{{What is observed instead.}}\n\n## Measurements\n\n| Metric | Baseline | Current | Delta |\n|---|---|---|---|\n| {{e.g. p95 latency}} | {{200ms}} | {{1.4s}} | {{+600%}} |\n| {{e.g. memory RSS}} | {{180MB}} | {{420MB}} | {{+133%}} |\n\n**Methodology:** {{How the numbers were taken — script, manual stopwatch,\nprofiler, load test. Be specific enough that a maintainer can reproduce.}}\n\n## Reproduction harness\n\n```\n{{Script, `tests/bench/...` reference, or numbered steps. Must be\ndeterministic enough to re-measure.}}\n```\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| First slow version (if known) | {{version or \"unknown\"}} |\n| Resource constraint hit | {{CPU / memory / network / FDs / \"none\"}} |\n\n## Logs / output\n\n```\n{{Relevant log lines or profiler output. SECRETS REDACTED.}}\n```\n\n## Additional context\n\n{{Anything else. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n\n<!-- File: .agents/skills/issue-create/assets/question.md (Tokens: ~243 | Category: anthropic-skill) -->\n<!--\nQuestion template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nNote: if it turns out to be a bug, switch to the bug-report template.\n-->\n\n## What I'm trying to accomplish\n\n{{The end goal, not the immediate confusion. e.g. \"I want to route\ngpt-5.5 traffic only to my work account\" — not \"what does\nplan_mapping do?\"}}\n\n## What I tried\n\n{{Commands, config snippets, docs read, search terms used. Be specific.}}\n\n```yaml\n# Relevant config — SECRETS REDACTED\n{{config snippet or \"none\"}}\n```\n\n## What I expected\n\n{{What outcome did you anticipate?}}\n\n## What happened\n\n{{What did you actually observe?}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n\n## Additional context\n\n{{Logs, screenshots, anything else. Remove if empty.}}\n\n<!-- File: .agents/skills/issue-create/references/issue-types.md (Tokens: ~750 | Category: anthropic-skill) -->\n# Issue Type Specs\n\nRequired and optional fields per issue type. The skill enforces \"required\" — every required field must have either an answer or an explicit \"not applicable\" / \"unknown\" before the issue can be filed.\n\n## Bug\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Becomes part of the title; ≤72 chars |\n| Expected behavior | yes | What the user thought would happen |\n| Actual behavior | yes | What actually happened |\n| Reproduction steps | yes | Numbered list, deterministic |\n| Codex-proxy version | yes | `npm pkg get version` or About dialog |\n| Deployment mode | yes | Electron / Docker / `npm start` / dev / source |\n| OS + arch | yes | e.g. macOS 14.5 arm64, Windows 11 x64, Ubuntu 22.04 x64 |\n| Relevant logs | yes | Redact secrets; \"none\" is acceptable |\n| Frequency | yes | always / intermittent / once |\n| Workaround | no | If the user found one |\n| First broken version | no | If known (helps bisect) |\n| Related issues | no | `Refs #N` |\n\n## Feature Request\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Title material |\n| Problem statement | yes | The user-facing motivation. NOT the proposed solution. |\n| Proposed solution | yes | High level; implementation detail is welcome but optional |\n| Alternatives considered | yes | Even \"I considered X but it doesn't fit because Y\" |\n| Who benefits | yes | single user / all users / specific deployment mode / specific upstream |\n| Impact if NOT done | no | Does the user have a workaround? Is this blocking? |\n| Related issues / PRs | no | `Refs #N` |\n| Mockups / sketches | no | For UI features |\n\n## Question\n\n| Field | Required | Notes |\n|---|---|---|\n| What you're trying to accomplish | yes | The end goal, not the immediate confusion |\n| What you tried | yes | Commands, config, links to docs read |\n| What you expected | yes | |\n| What happened | yes | |\n| Relevant config | yes | Redact secrets; \"none\" if no config involved |\n| Codex-proxy version | yes | |\n| Deployment mode | yes | |\n\nIf a \"question\" turns out to be a bug during the interview, switch to the Bug template — do not file under `question`.\n\n## Performance\n\nAll Bug fields, plus:\n\n| Field | Required | Notes |\n|---|---|---|\n| Baseline measurement | yes | Numbers from a known-good version or expected baseline |\n| Current measurement | yes | Same metric, current version |\n| Measurement methodology | yes | How the numbers were taken — script, manual stopwatch, profiler |\n| Reproduction harness | yes | Script, `tests/bench/...` reference, or steps |\n| Resource constraint hit | no | CPU, memory, network, file descriptors, etc. |\n\nA perf report without numbers is a bug report — switch templates.\n\n## Documentation\n\n| Field | Required | Notes |\n|---|---|---|\n| Doc location | yes | File path (`README.md`, `CLAUDE.md`, `docs/...`) or URL |\n| What is wrong / missing | yes | Specific quote of the offending text, or \"this section is missing\" |\n| Suggested fix | no | Welcome but not required |\n| Audience affected | no | New users / operators / contributors / API consumers |\n\n<!-- File: .agents/skills/issue-create/references/labels.md (Tokens: ~471 | Category: anthropic-skill) -->\n# Issue Labels (codex-proxy)\n\nThe complete catalog of labels currently defined on the repo. Apply only labels from this list — do not invent new ones. To propose a new label, file a `chore:` issue separately.\n\n| Label | Color | Use for |\n|---|---|---|\n| `bug` | #d73a4a | Something isn't working as documented or intended |\n| `enhancement` | #a2eeef | New feature or extension of an existing feature |\n| `documentation` | #0075ca | Improvements or additions to documentation |\n| `question` | #d876e3 | Further information is requested; not yet known to be a bug |\n| `help wanted` | #008672 | Maintainers welcome contributors to take this on |\n| `good first issue` | #7057ff | Small scope, low context required, friendly to newcomers |\n| `duplicate` | #cfd3d7 | Already filed elsewhere — set after triage, not on creation |\n| `invalid` | #e4e669 | Not actionable or out of scope — set after triage |\n| `wontfix` | #ffffff | Acknowledged but will not be addressed — set after triage |\n| `sync-conflict` | #d73a4a | `main → electron` auto-sync merge conflict — used by automation, not for human-filed issues |\n\n## Application rules for the skill\n\n1. **One type label minimum**: bug / enhancement / documentation / question (pick exactly one based on the issue type).\n2. **`good first issue`**: only when the user explicitly confirms the scope is small AND the fix is local (single file or single module).\n3. **`help wanted`**: when the reporter has no plan to send a PR themselves.\n4. **`documentation`** can be combined with `bug` or `enhancement` if the change requires both code and doc updates.\n5. **Never apply on creation**: `duplicate`, `invalid`, `wontfix`, `sync-conflict`. These are triage / automation labels.\n\n## CLI form\n\n```bash\ngh issue create --label \"bug,help wanted\" ...\n```\n\nMultiple labels are comma-separated (no space after the comma).\n\n<!-- File: .agents/skills/issue-create/SKILL.md (Tokens: ~1771 | Category: anthropic-skill) -->\n---\nname: issue-create\ndescription: >-\n  Interview the user to gather all required context, then open a high-quality GitHub issue (`gh issue create`) on the codex-proxy repo with the right template, labels, and structured body.\n  TRIGGER when: user says \"open an issue\", \"file an issue\", \"create issue\", \"report a bug\", \"feature request\", \"提个 issue\", \"报 bug\", \"提需求\".\n  DO NOT TRIGGER when: user wants to view, search, comment on, or close existing issues (use `gh issue list/view/comment/close` directly); user is writing a PR description (use `pr-push`).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Write\"\n---\n\n# Issue Create\n\nGather complete context through a structured interview, then file a well-formed issue. The interview is a hard gate — vague issues waste maintainer time.\n\n## Overview\n\nMost \"I have a bug\" or \"I want a feature\" reports are missing the information a maintainer needs to act. This skill runs a four-phase interview, fills the appropriate template, applies the right labels, and only then calls `gh issue create`. The user sees and approves the rendered body before submission.\n\n## When to Use\n\n- A user wants to file a new issue on the codex-proxy repository.\n- A user describes a bug or feature in conversation and asks \"should we file an issue?\"\n\n## Important Rules\n\n1. **The interview is not optional.** Do NOT call `gh issue create` until all required fields for the chosen type are collected and the user has explicitly approved the rendered body.\n2. **Never invent reproduction steps, version numbers, log output, or behavior.** If the user did not provide it, ask. If they cannot provide it, write \"not provided\" in the field, do not fabricate.\n3. **Show the full body before submitting.** The user must explicitly say \"submit\" / \"looks good\" / equivalent. \"Yes\" without seeing the body is not enough — show it first.\n4. **Apply only labels from the project's existing label set.** Read `references/labels.md` for the catalog. Do not invent new labels.\n5. **Strip secrets.** If the user pastes logs, headers, or config that contain tokens, cookies, OAuth state, API keys, or account IDs, redact them before they enter the issue body. Replace with `<redacted>`.\n6. **One issue per scope.** If the user describes two unrelated problems, file two issues. Ask before splitting.\n\n## Key Workflows\n\n### Phase 1: Type classification\n\n**Goal:** Pick the right template and label.\n\nAsk the user (one consolidated question):\n\n> What type of issue is this?\n>   1. **Bug** — something is broken or behaves incorrectly\n>   2. **Feature request** — propose new functionality\n>   3. **Question** — usage / configuration / \"is this expected?\"\n>   4. **Performance** — measurable regression or slowness\n>   5. **Documentation** — docs are wrong, missing, or unclear\n\nRead the type spec:\n```\nRead: .Codex/skills/issue-create/references/issue-types.md\n```\n\nMap answer to template path:\n\n| Type | Template asset | Default label |\n|---|---|---|\n| Bug | `assets/bug-report.md` | `bug` |\n| Feature request | `assets/feature-request.md` | `enhancement` |\n| Question | `assets/question.md` | `question` |\n| Performance | `assets/perf-report.md` | `bug` |\n| Documentation | `assets/feature-request.md` (with docs framing) | `documentation` |\n\nDo **NOT** proceed to Phase 2 until the type is confirmed.\n\n### Phase 2: Required-field interview\n\n**Goal:** Collect every field the chosen template requires.\n\nRead `references/issue-types.md` to see the required-field table for the chosen type. Ask for missing fields in **one consolidated message**, not one at a time. Group related fields together.\n\n**For bugs**, the required fields are:\n- One-line summary\n- Expected behavior\n- Actual behavior\n- Reproduction steps (numbered)\n- Codex-proxy version (`npm pkg get version` or app About dialog)\n- Deployment mode (Electron app / Docker / `npm start` / dev)\n- Relevant log lines (redact secrets)\n- Frequency (always / intermittent / once)\n\n**For feature requests**, the required fields are:\n- Problem the feature solves (user-facing motivation, not the proposed solution)\n- Proposed solution (high level)\n- Alternatives considered\n- Who benefits (single user / all users / specific deployment mode)\n\n**For questions**:\n- What you tried\n- What you expected\n- What happened\n- Relevant config (redact secrets)\n\n**For performance**:\n- All bug fields, plus:\n- Measured baseline vs current (timings, memory, request count — be specific)\n- Reproduction harness (script, steps, or `tests/bench/`)\n\n**For documentation**:\n- Which doc page / file\n- What is wrong or missing\n- Suggested fix (if any)\n\nIf a field cannot be answered, the user must explicitly say \"not applicable\" or \"unknown\" — record that verbatim. Do not silently skip.\n\nDo **NOT** proceed to Phase 3 until every required field has either an answer or an explicit \"not applicable\".\n\n### Phase 3: Code & related-context grounding\n\n**Goal:** Help maintainers find the relevant code fast.\n\nAsk the user for:\n- File paths or `file:line` references they suspect are involved (optional but encouraged).\n- Related issues / PRs to link (`Refs #N`, `Related to #N`).\n- Whether they tried searching existing issues (`gh issue list --search \"<keywords>\"`). If they have not and the report sounds like something that might exist, run the search and show top 3 matches before continuing.\n\nIf the user provides no code locations and the bug is concrete, optionally offer:\n> \"Want me to grep for the relevant code so we can include file:line in the issue?\"\n\nDo not grep silently — ask first, and only do it once.\n\n### Phase 4: Render, confirm, submit\n\n**Goal:** Show the final body, get explicit approval, file the issue.\n\n1. Read the chosen template:\n   ```\n   Read: .Codex/skills/issue-create/assets/<template>.md\n   ```\n2. Read the labels catalog:\n   ```\n   Read: .Codex/skills/issue-create/references/labels.md\n   ```\n3. Fill the template with the collected fields. Strip secrets per Important Rule #5.\n4. Pick labels:\n   - Always include the type label (Phase 1 mapping).\n   - Add `good first issue` only if the user explicitly says it qualifies (small scope, low context required).\n   - Add `help wanted` if the user has no plan to fix it themselves.\n   - Add `documentation` in addition to the type label if docs need updating.\n5. Show the user the complete rendered output:\n   ```\n   Title: <title>\n   Labels: <label1>, <label2>\n   Body:\n   <full body>\n   ```\n6. Ask: \"Ready to submit, or want to adjust anything?\"\n7. Wait for an explicit affirmative. \"Yes\", \"submit\", \"go\", \"looks good\", \"提交\" all qualify. Silence or hedging does not.\n8. Submit:\n   ```bash\n   gh issue create \\\n     --title \"<title>\" \\\n     --label \"<label1>,<label2>\" \\\n     --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n9. Print the issue URL.\n10. **STOP.** Do not assign, do not comment, do not link to projects unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not call `gh issue create` before showing the body for approval.\n- Do not invent reproduction steps when the user gave a vague report — ask.\n- Do not paste raw logs that contain tokens / cookies / OAuth state / account IDs.\n- Do not apply labels outside the existing catalog.\n- Do not file two issues from one report without confirming the split with the user.\n- Do not grep / search the codebase silently to \"fill in\" missing fields — ask first.\n\n<!-- File: .agents/skills/pr-push/assets/pr-body-template.md (Tokens: ~340 | Category: anthropic-skill) -->\n<!--\nPR body template for codex-proxy. The skill fills in the {{placeholders}}\nand removes optional sections that don't apply. Default language follows\nthe repo's dominant language (currently zh-CN for CHANGELOG entries,\nen for code/commits). Pick one and stay consistent within a single PR.\n-->\n\n## Summary\n\n{{One paragraph: WHAT changed and WHY. Reference the user-visible impact.\nIf multiple commits, summarize the branch's intent, not each commit.}}\n\n## Changes\n\n{{Bulleted list mirroring the CHANGELOG entry. Group by area when the PR\ntouches multiple modules. Reference file paths so reviewers can navigate.}}\n\n- {{change 1 — files}}\n- {{change 2 — files}}\n\n## Test Plan\n\n{{List the commands actually run locally. Do not invent results.\nMark checked items with [x], unchecked with [ ].}}\n\n- [ ] `npm test`\n- [ ] `npm run build`\n- [ ] {{any feature-specific manual verification, e.g. \"Verified Dashboard 用量页 cache hit card renders with mock data\"}}\n- [ ] {{`npm run test:real` if the change touches upstream protocol}}\n\n## Notes\n\n{{Optional. Use for any of:\n - Reviewer attention requests (\"please double-check the SSE buffer math in src/...\")\n - Known follow-ups (\"memory entry for new RT format will land in a separate PR\")\n - Migration / config impact (\"operators must add `update.allow_prerelease` if they want beta\")\n - Screenshots for UI changes\nRemove this section if there are no notes.}}\n\n## Linked Issues\n\n{{Closes #N / Refs #N — remove if none.}}\n\n<!-- File: .agents/skills/pr-push/references/changelog-format.md (Tokens: ~633 | Category: anthropic-skill) -->\n# CHANGELOG Format\n\nCodex-proxy follows [Keep a Changelog](https://keepachangelog.com/). Every PR that changes user-visible behavior, public API, configuration, or build/release infrastructure MUST add an entry to `CHANGELOG.md` under `## [Unreleased]`.\n\n## Section Layout\n\n`## [Unreleased]` contains exactly these subsections (in this order, omit empty ones):\n\n```markdown\n## [Unreleased]\n\n### Changed\n\n- ...\n\n### Added\n\n- ...\n\n### Fixed\n\n- ...\n```\n\n| Subsection | Use for |\n|---|---|\n| `### Added` | New features, new endpoints, new config keys, new CLI flags |\n| `### Changed` | Behavior change of existing features, default value changes, signature changes |\n| `### Fixed` | Bug fixes |\n| `### Removed` | Deleted features (rare; gate behind a deprecation cycle first) |\n| `### Deprecated` | Marking something for future removal |\n| `### Security` | Security-relevant fix (CVE, cred leak, etc.) |\n\n## Entry Style\n\n- Use the same language as the existing `[Unreleased]` entries (zh-CN at time of writing). If the file flips to English, follow.\n- Lead with the user-visible impact, then mention the file paths in parentheses for reviewer navigation.\n- Reference issues / PRs with `(#NNN)` inline.\n- Multi-aspect entries get nested bullets.\n\n## Examples (from current `[Unreleased]`)\n\n```markdown\n### Added\n\n- 图像生成请求计数（成功 / 失败分流）：`AccountUsage` 新增 `image_request_count` / `image_request_failed_count`...\n- Dashboard 用量统计新增「缓存命中率」卡片...\n```\n\n```markdown\n### Changed\n\n- `bump-electron-beta.yml` 触发改为定时 cron（每天 04:00 / 12:00 UTC）...\n```\n\n## When NOT to add a CHANGELOG entry\n\nSkip CHANGELOG for commits that are:\n\n- Test-only (`test:` prefix) — no user impact\n- Doc-only edits to internal docs (`CLAUDE.md`, `.claude/`, `docs/dev-notes/`)\n- Pure refactors that change zero observed behavior (`refactor:` prefix with no API surface change)\n- CI-only changes that do not affect built artifacts (`ci:` prefix)\n- Style/formatting (`style:` prefix)\n\nIf unsure, **add the entry**. A redundant entry is cheaper than a missing one.\n\n## Multi-line / multi-bullet entries\n\nUse the existing nested bullet pattern:\n\n```markdown\n- Ollama bridge cleanup (#403 review followups, closes #405 #406 #407):\n  - `src/ollama/bridge.ts` 不再重复实现 `normalizeHostname`...\n  - `proxyOpenAIRequest` 转发头扩展到...\n  - `MAX_SSE_BUFFER` 重命名为 `MAX_SSE_BUFFER_CHARS`...\n```\n\n<!-- File: .agents/skills/pr-push/references/commit-conventions.md (Tokens: ~670 | Category: anthropic-skill) -->\n# Commit Message Conventions\n\nCodex-proxy uses Conventional Commits with a fixed type vocabulary. Several CI workflows pattern-match on the type prefix, so unknown types break automation.\n\n## Format\n\n```\n<type>(<optional scope>): <imperative summary>\n\n<optional body — wrap at ~72 cols, explain WHY>\n\n<optional footer — Closes #N, Refs #N, BREAKING CHANGE: ...>\n```\n\n- Subject is **imperative mood**, lowercase first letter, no trailing period.\n- Subject ≤ 72 chars hard cap.\n- Body explains *why* the change was made, not *what* (the diff shows what).\n\n## Type Vocabulary\n\n| Type | Use for | Triggers beta release? |\n|---|---|---|\n| `feat` | New user-visible feature | yes |\n| `fix` | Bug fix | yes |\n| `perf` | Performance improvement with no behavior change | yes |\n| `refactor` | Code restructuring with no behavior change | no |\n| `docs` | Documentation only | no |\n| `test` | Test-only changes | no |\n| `chore` | Tooling, dependencies, repo housekeeping | no |\n| `ci` | CI/CD configuration | no |\n| `style` | Formatting, whitespace, no logic change | no |\n\nThe \"Triggers beta release?\" column is determined by `bump-electron-beta.yml`'s skip filter: `^(chore|docs|ci|test|refactor|style)`. Note that `fix(ci):` still triggers a beta release because the prefix is `fix`.\n\n## Scope\n\nOptional, but encouraged for clarity. Use the top-level module name:\n\n- `feat(auth): ...`\n- `fix(translation): ...`\n- `refactor(routes): ...`\n- `chore(deps): ...`\n- `ci(release): ...`\n\nSkip the scope when the change spans multiple modules or is genuinely repo-wide.\n\n## Examples\n\nGood:\n\n```\nfeat(auth): persist account-pool RT-only imports across restarts\n```\n\n```\nfix(translation): recover from previous_response_not_found instead of passing it through\n```\n\n```\nrefactor(routes): extract shared proxy-handler from openai/anthropic/gemini handlers\n```\n\nBad — and why:\n\n| Message | Why it fails |\n|---|---|\n| `Update auth.ts` | No type, describes WHAT not WHY |\n| `feat: Added new feature.` | Past tense + capitalized + trailing period |\n| `feature(auth): persist RT` | `feature` is not in the vocabulary, use `feat` |\n| `fix: stuff` | Subject is meaningless |\n| `wip` | No type, no information |\n\n## Multi-line body\n\nUse a HEREDOC to preserve formatting:\n\n```bash\ngit commit -m \"$(cat <<'EOF'\nfix(quota): ignore stale x-codex-* headers after token refresh\n\nThe previous behavior overwrote fresh quota state with cached headers\nfrom the old token, causing accounts to appear over-quota for ~30s\nafter refresh. Now we drop quota updates whose token id does not match\nthe current session.\n\nCloses #418\nEOF\n)\"\n```\n\n<!-- File: .agents/skills/pr-push/references/pr-checklist.md (Tokens: ~644 | Category: anthropic-skill) -->\n# Pre-PR Self-Check\n\nWalk this list before opening the PR. Anything left unchecked needs a written reason in the PR body.\n\n## Branch & target\n\n- [ ] Current branch is NOT `dev` or `main`\n- [ ] Branch is rebased on (or fast-forwardable to) `origin/dev`\n- [ ] PR target = `dev`\n\n## Commit hygiene\n\n- [ ] Each commit follows `<type>(<scope>): <summary>` with a vocabulary type (see `commit-conventions.md`)\n- [ ] No commit was created with `--no-verify`\n- [ ] No file added with `git add -f`\n- [ ] No accidental staging of `node_modules/`, `dist/`, `*.log`, `.env*`, `data/`, or other gitignored paths\n- [ ] No secrets in code or commit messages (API keys, tokens, cookies, oauth_state)\n\n## CHANGELOG\n\n- [ ] If the change touches `src/`, `shared/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` → `CHANGELOG.md` `[Unreleased]` has a new entry\n- [ ] Entry placed in correct subsection (Added / Changed / Fixed)\n- [ ] Entry references the issue / PR number when applicable\n\n## Cross-artifact impact\n\nCodex-proxy ships three artifacts: backend (Docker), Electron desktop, web frontend. The pre-push hook will catch most of these, but verify mentally first:\n\n- [ ] If `src/` changed → backend logic still passes `npm test`\n- [ ] If `web/` changed → `npm run build` produces a clean Vite bundle\n- [ ] If `Dockerfile` / `docker-compose*` changed → image still builds\n- [ ] If `packages/electron/**` or `electron-builder.yml` changed → Electron config validates\n- [ ] If `native/**` changed → native addon still builds\n\n## Tests\n\n- [ ] New behavior has new tests (TDD: tests written first when feasible)\n- [ ] All affected `npm test` suites pass locally\n- [ ] No `*.skip` left behind unless explicitly justified in the PR body\n\n## TypeScript\n\n- [ ] No `any`, `as any`, `: any`, or `<any>` in new code (use `unknown`, generics, or specific types)\n- [ ] No `@ts-ignore` / `@ts-expect-error` without an inline explanation comment\n\n## Real-upstream changes\n\n- [ ] If the change touches the upstream protocol (translation/, proxy/, auth/), `npm run test:real` was attempted at least once\n\n## Documentation\n\n- [ ] Public-facing config/flag changes are reflected in `config/default.yaml` comments and `CLAUDE.md` if relevant\n- [ ] No internal personal notes leaked into committed files\n\n## After push (do NOT do these in this skill)\n\n- [ ] Wait for CI green before requesting review\n- [ ] Merge is a separate, explicit decision — never auto-merge from this skill\n\n<!-- File: .agents/skills/pr-push/SKILL.md (Tokens: ~2335 | Category: anthropic-skill) -->\n---\nname: pr-push\ndescription: >-\n  Package the current working changes into a standards-compliant codex-proxy pull request:\n  branch hygiene, commit message linting, CHANGELOG prompt, conventional commit, push, and `gh pr create` against the `dev` branch.\n  TRIGGER when: user asks to \"push a PR\", \"open a PR\", \"create PR\", \"ship this\", \"推 PR\", \"开 PR\", \"提交 PR\".\n  DO NOT TRIGGER when: user only wants to commit without pushing; user explicitly wants to push directly to main; user wants to merge, rebase, or close an existing PR (use `gh pr merge` / `gh pr close` directly).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Edit\"\n  - \"Write\"\n  - \"Grep\"\n---\n\n# PR Push\n\nTurn the current working tree into a clean PR targeting `dev`. This skill enforces codex-proxy's contribution rules so community maintainers do not have to memorize them.\n\n## Overview\n\nCodex-proxy uses a `dev` → `main` promotion flow with strict commit conventions, CHANGELOG discipline, and a pre-push validation hook. This skill walks the maintainer through an interview, makes the commit, runs the push (letting the hook gate quality), and opens the PR. It explicitly stops before merge — review and merge are separate human decisions.\n\n## When to Use\n\n- A maintainer has finished a unit of work in their working tree and wants it on `dev`.\n- A maintainer asks to \"open a PR\" or equivalent and the working tree has changes (staged, unstaged, or untracked).\n\n## Important Rules\n\n1. **Target branch is always `dev`.** Never open a PR against `main` unless the user explicitly states \"target main\" with a written reason. The `main` branch is fast-forwarded by the `promote-dev-to-main.yml` workflow — manual PRs to `main` break that contract.\n2. **Never commit on `dev` or `main` directly.** If `git branch --show-current` is one of these, stop and ask the user to name a feature branch (`git switch -c <name>`).\n3. **Never use `git add -A`, `git add .`, or `git add -f`.** Stage files by explicit path. `-f` overrides `.gitignore` and has been the cause of secret leaks elsewhere.\n4. **Never pass `--no-verify` to `git commit` or `git push`.** The hook is the gate. If it fails, fix the underlying issue, do not bypass.\n5. **Stop after `gh pr create`.** Do not merge, do not approve, do not enable auto-merge. Pushing a PR and merging a PR are two human decisions.\n6. **CHANGELOG gate.** If any file under `src/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` changed, `CHANGELOG.md`'s `[Unreleased]` section MUST have a new entry covering the change before the commit is created.\n7. **Commit message format is fixed:** `<type>(<optional-scope>): <imperative summary>`. The type set is enumerated in `references/commit-conventions.md`.\n\n## Key Workflows\n\n### Phase 1: Discovery (interview, do not touch the repo yet)\n\n**Goal:** Understand what is being shipped before any git operation.\n\nRun these read-only commands in parallel and summarize results back to the user:\n\n```\ngit branch --show-current\ngit status --short\ngit diff --stat\ngit log --oneline -10\n```\n\nThen read the conventions:\n```\nRead: .Codex/skills/pr-push/references/commit-conventions.md\nRead: .Codex/skills/pr-push/references/changelog-format.md\nRead: .Codex/skills/pr-push/references/pr-checklist.md\n```\n\nAsk the user (in one consolidated message) for any field that cannot be inferred:\n\n- **Commit type** (feat / fix / refactor / docs / test / chore / perf / ci) — propose one based on the diff, ask for confirmation.\n- **One-line summary** (imperative, lowercase, no trailing period) — propose one based on the diff.\n- **PR target** — default `dev`. Confirm only if the user previously asked to deviate.\n- **CHANGELOG entry** — if the gate in Important Rules #6 applies and `CHANGELOG.md` `[Unreleased]` has no matching entry, ask the user to dictate one (or offer to draft one for review). Do not invent silently.\n- **Memory / docs touch** — if the change touches public protocol, request flow, auth lifecycle, or release infra, ask whether `AGENTS.md` needs updating in the same PR.\n\nDo **NOT** proceed to Phase 2 until the user has explicitly confirmed (a) commit type, (b) summary, (c) CHANGELOG status, (d) target = `dev`.\n\n### Phase 2: Branch hygiene\n\n**Goal:** Make sure the commit lands on a feature branch, not on `dev`/`main`.\n\n1. Check `git branch --show-current`.\n2. If the current branch is `dev` or `main`:\n   - Stop. Ask the user to provide a feature branch name (suggest one derived from the commit summary, kebab-case, ≤40 chars).\n   - Run `git switch -c <name>`. Do not auto-pick a name without confirmation.\n3. If the current branch is a feature branch but is not based on up-to-date `origin/dev`:\n   - Run `git fetch origin dev`.\n   - If `git merge-base --is-ancestor origin/dev HEAD` is false (branch is behind), warn the user and ask whether to `git rebase origin/dev` before continuing. Do not rebase silently.\n\n### Phase 3: Stage + commit\n\n**Goal:** Produce one well-formed commit.\n\n1. List the files the user wants in this commit. If they didn't say, propose the list from `git status --short` and confirm.\n2. Run `git add <file1> <file2> ...` with explicit paths. Never `-A`, `.`, or `-f`.\n3. If CHANGELOG was updated as part of Phase 1, include `CHANGELOG.md` in the staged set.\n4. Build the commit message:\n   - First line: `<type>(<scope>): <summary>` — scope is optional, omit parentheses if no scope.\n   - Body (optional): wrap at ~72 cols, explain *why*, reference issues with `Closes #N` / `Refs #N` if applicable.\n5. Commit with a HEREDOC (preserves formatting):\n   ```bash\n   git commit -m \"$(cat <<'EOF'\n   <type>(<scope>): <summary>\n\n   <optional body>\n   EOF\n   )\"\n   ```\n6. If the commit fails because of a pre-commit hook, fix the reported issue and create a NEW commit (do not `--amend`). Re-run the same command after fixes.\n\n### Phase 4: Push\n\n**Goal:** Get the branch to `origin` so a PR can be opened.\n\n1. Confirm the user wants to push (a single short \"ready to push?\" — they may have wanted to inspect the commit first).\n2. **Hook presence check.** The repo's pre-push gate lives at `.Codex/hooks/pre-push-validate.sh`, which is gitignored — fresh clones do **not** have it. Run `test -x .Codex/hooks/pre-push-validate.sh`:\n   - **Hook present** → push normally; the hook will run.\n   - **Hook missing** → warn the user that no pre-push gate is installed, then run the equivalent checks inline based on what the diff touched, before pushing:\n     | Diff touches | Run |\n     |---|---|\n     | `src/**` or `tests/**` | `npm test` and `npx tsc --noEmit` |\n     | `web/**` | `npm run build` |\n     | `Dockerfile`, `docker-compose*` | `docker build .` (or note user must verify) |\n     | `packages/electron/**`, `electron-builder.yml` | `npm run -w packages/electron build` |\n     | `native/**` | `npm run -w native build` |\n     Any failure aborts the push — fix and re-run.\n3. Run `git push -u origin HEAD`.\n4. If the push is blocked by the hook:\n   - Read the hook output verbatim back to the user.\n   - The hook validates the build targets affected by the diff (test, tsc, web build, Dockerfile lint, Electron config, native addon). Identify which target failed and propose a fix.\n   - **Never retry with `--no-verify`.** Re-run the offending check locally, fix the root cause, amend the commit only if the user authorizes it, otherwise add a fix-up commit.\n\n### Phase 5: Open the PR\n\n**Goal:** Create a PR against `dev` with a body that future reviewers can read cold.\n\n1. Read the PR body template:\n   ```\n   Read: .Codex/skills/pr-push/assets/pr-body-template.md\n   ```\n2. Determine PR title:\n   - If the branch has a single commit, reuse the commit subject.\n   - If multiple commits, propose a title that summarizes the branch's intent and confirm with user.\n   - Title MUST start with a conventional type, MUST be ≤72 chars.\n3. Fill the body sections (Summary / Test Plan / Notes). Source content from:\n   - `git log <base>..HEAD` for the change list.\n   - The CHANGELOG entry the user wrote.\n   - Test commands actually run locally (do not invent test results).\n4. Show the rendered title + body to the user. **Wait for explicit \"looks good\" before invoking `gh`.**\n5. Create the PR:\n   ```bash\n   gh pr create --base dev --title \"<title>\" --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n6. Print the PR URL.\n7. **STOP.** Do not run `gh pr merge`, `gh pr review --approve`, `gh pr edit --add-label`, or `--auto-merge` unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not assume the user wants every modified file in the PR — ask.\n- Do not auto-write the CHANGELOG entry without showing it for approval first.\n- Do not retry a failing pre-push hook with `--no-verify`.\n- Do not open the PR against `main` even if the user is on a branch named `main-fix-X` — branch name does not imply target.\n- Do not silently rebase. If the branch needs rebase against `origin/dev`, ask first.\n- Do not chain `gh pr create` with `gh pr merge`. Two separate decisions.\n\n<!-- File: .claude/skills/issue-create/assets/bug-report.md (Tokens: ~291 | Category: anthropic-skill) -->\n<!--\nBug report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nMatch the language of the repo's existing issues (currently a mix of zh-CN and en).\n-->\n\n## Summary\n\n{{One sentence describing the bug.}}\n\n## Expected behavior\n\n{{What the user thought would happen.}}\n\n## Actual behavior\n\n{{What actually happened.}}\n\n## Reproduction steps\n\n1. {{step 1}}\n2. {{step 2}}\n3. {{step 3 — describe the failure}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| Frequency | {{always / intermittent / once}} |\n| First broken version (if known) | {{version or \"unknown\"}} |\n| Workaround (if any) | {{description or \"none\"}} |\n\n## Logs / output\n\n```\n{{Paste relevant log lines. SECRETS REDACTED — no tokens, cookies,\noauth_state, API keys, account IDs.}}\n```\n\n## Additional context\n\n{{Anything else the maintainer should know. Remove this section if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n\n<!-- File: .claude/skills/issue-create/assets/feature-request.md (Tokens: ~272 | Category: anthropic-skill) -->\n<!--\nFeature request template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\n-->\n\n## Summary\n\n{{One sentence describing the feature.}}\n\n## Problem\n\n{{The user-facing motivation. What can the user not do today, or what is\npainful about how they have to do it? DO NOT describe the proposed\nsolution here — only the problem.}}\n\n## Proposed solution\n\n{{High-level description of how the feature would work. Implementation\ndetail is welcome but not required. If you have a UI in mind, sketch\nor screenshot helps.}}\n\n## Alternatives considered\n\n{{Other approaches the user thought about and why they don't fit.\nEven \"I considered X but it doesn't work because Y\" is useful — it\nsaves the maintainer from re-deriving the same conclusion.}}\n\n## Who benefits\n\n{{single user / all users / a specific deployment mode (Electron / Docker / dev) /\na specific upstream provider / a specific account state}}\n\n## Impact if not done\n\n{{Does the user have a workaround? Is this blocking? Nice-to-have?\nRemove this section if \"no impact, just nice\".}}\n\n## Additional context\n\n{{Mockups, links, related discussions. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n\n<!-- File: .claude/skills/issue-create/assets/perf-report.md (Tokens: ~404 | Category: anthropic-skill) -->\n<!--\nPerformance report template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nA perf report without numbers is just a bug — switch to bug-report.md if\nno measurements are available.\n-->\n\n## Summary\n\n{{One sentence describing the regression or slowness.}}\n\n## Expected behavior\n\n{{What performance was expected, and where that expectation comes from\n(prior version, docs, comparable system).}}\n\n## Actual behavior\n\n{{What is observed instead.}}\n\n## Measurements\n\n| Metric | Baseline | Current | Delta |\n|---|---|---|---|\n| {{e.g. p95 latency}} | {{200ms}} | {{1.4s}} | {{+600%}} |\n| {{e.g. memory RSS}} | {{180MB}} | {{420MB}} | {{+133%}} |\n\n**Methodology:** {{How the numbers were taken — script, manual stopwatch,\nprofiler, load test. Be specific enough that a maintainer can reproduce.}}\n\n## Reproduction harness\n\n```\n{{Script, `tests/bench/...` reference, or numbered steps. Must be\ndeterministic enough to re-measure.}}\n```\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2 or commit SHA}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n| First slow version (if known) | {{version or \"unknown\"}} |\n| Resource constraint hit | {{CPU / memory / network / FDs / \"none\"}} |\n\n## Logs / output\n\n```\n{{Relevant log lines or profiler output. SECRETS REDACTED.}}\n```\n\n## Additional context\n\n{{Anything else. Remove if empty.}}\n\n## Related\n\n{{Refs #N, Related to #N — remove if none.}}\n\n<!-- File: .claude/skills/issue-create/assets/question.md (Tokens: ~243 | Category: anthropic-skill) -->\n<!--\nQuestion template for codex-proxy issues.\nThe issue-create skill fills in {{placeholders}}.\nNote: if it turns out to be a bug, switch to the bug-report template.\n-->\n\n## What I'm trying to accomplish\n\n{{The end goal, not the immediate confusion. e.g. \"I want to route\ngpt-5.5 traffic only to my work account\" — not \"what does\nplan_mapping do?\"}}\n\n## What I tried\n\n{{Commands, config snippets, docs read, search terms used. Be specific.}}\n\n```yaml\n# Relevant config — SECRETS REDACTED\n{{config snippet or \"none\"}}\n```\n\n## What I expected\n\n{{What outcome did you anticipate?}}\n\n## What happened\n\n{{What did you actually observe?}}\n\n## Environment\n\n| Field | Value |\n|---|---|\n| Codex-proxy version | {{e.g. 1.4.2}} |\n| Deployment mode | {{Electron / Docker / `npm start` / dev}} |\n| OS + arch | {{e.g. macOS 14.5 arm64}} |\n\n## Additional context\n\n{{Logs, screenshots, anything else. Remove if empty.}}\n\n<!-- File: .claude/skills/issue-create/references/issue-types.md (Tokens: ~750 | Category: anthropic-skill) -->\n# Issue Type Specs\n\nRequired and optional fields per issue type. The skill enforces \"required\" — every required field must have either an answer or an explicit \"not applicable\" / \"unknown\" before the issue can be filed.\n\n## Bug\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Becomes part of the title; ≤72 chars |\n| Expected behavior | yes | What the user thought would happen |\n| Actual behavior | yes | What actually happened |\n| Reproduction steps | yes | Numbered list, deterministic |\n| Codex-proxy version | yes | `npm pkg get version` or About dialog |\n| Deployment mode | yes | Electron / Docker / `npm start` / dev / source |\n| OS + arch | yes | e.g. macOS 14.5 arm64, Windows 11 x64, Ubuntu 22.04 x64 |\n| Relevant logs | yes | Redact secrets; \"none\" is acceptable |\n| Frequency | yes | always / intermittent / once |\n| Workaround | no | If the user found one |\n| First broken version | no | If known (helps bisect) |\n| Related issues | no | `Refs #N` |\n\n## Feature Request\n\n| Field | Required | Notes |\n|---|---|---|\n| One-line summary | yes | Title material |\n| Problem statement | yes | The user-facing motivation. NOT the proposed solution. |\n| Proposed solution | yes | High level; implementation detail is welcome but optional |\n| Alternatives considered | yes | Even \"I considered X but it doesn't fit because Y\" |\n| Who benefits | yes | single user / all users / specific deployment mode / specific upstream |\n| Impact if NOT done | no | Does the user have a workaround? Is this blocking? |\n| Related issues / PRs | no | `Refs #N` |\n| Mockups / sketches | no | For UI features |\n\n## Question\n\n| Field | Required | Notes |\n|---|---|---|\n| What you're trying to accomplish | yes | The end goal, not the immediate confusion |\n| What you tried | yes | Commands, config, links to docs read |\n| What you expected | yes | |\n| What happened | yes | |\n| Relevant config | yes | Redact secrets; \"none\" if no config involved |\n| Codex-proxy version | yes | |\n| Deployment mode | yes | |\n\nIf a \"question\" turns out to be a bug during the interview, switch to the Bug template — do not file under `question`.\n\n## Performance\n\nAll Bug fields, plus:\n\n| Field | Required | Notes |\n|---|---|---|\n| Baseline measurement | yes | Numbers from a known-good version or expected baseline |\n| Current measurement | yes | Same metric, current version |\n| Measurement methodology | yes | How the numbers were taken — script, manual stopwatch, profiler |\n| Reproduction harness | yes | Script, `tests/bench/...` reference, or steps |\n| Resource constraint hit | no | CPU, memory, network, file descriptors, etc. |\n\nA perf report without numbers is a bug report — switch templates.\n\n## Documentation\n\n| Field | Required | Notes |\n|---|---|---|\n| Doc location | yes | File path (`README.md`, `CLAUDE.md`, `docs/...`) or URL |\n| What is wrong / missing | yes | Specific quote of the offending text, or \"this section is missing\" |\n| Suggested fix | no | Welcome but not required |\n| Audience affected | no | New users / operators / contributors / API consumers |\n\n<!-- File: .claude/skills/issue-create/references/labels.md (Tokens: ~471 | Category: anthropic-skill) -->\n# Issue Labels (codex-proxy)\n\nThe complete catalog of labels currently defined on the repo. Apply only labels from this list — do not invent new ones. To propose a new label, file a `chore:` issue separately.\n\n| Label | Color | Use for |\n|---|---|---|\n| `bug` | #d73a4a | Something isn't working as documented or intended |\n| `enhancement` | #a2eeef | New feature or extension of an existing feature |\n| `documentation` | #0075ca | Improvements or additions to documentation |\n| `question` | #d876e3 | Further information is requested; not yet known to be a bug |\n| `help wanted` | #008672 | Maintainers welcome contributors to take this on |\n| `good first issue` | #7057ff | Small scope, low context required, friendly to newcomers |\n| `duplicate` | #cfd3d7 | Already filed elsewhere — set after triage, not on creation |\n| `invalid` | #e4e669 | Not actionable or out of scope — set after triage |\n| `wontfix` | #ffffff | Acknowledged but will not be addressed — set after triage |\n| `sync-conflict` | #d73a4a | `master → electron` auto-sync merge conflict — used by automation, not for human-filed issues |\n\n## Application rules for the skill\n\n1. **One type label minimum**: bug / enhancement / documentation / question (pick exactly one based on the issue type).\n2. **`good first issue`**: only when the user explicitly confirms the scope is small AND the fix is local (single file or single module).\n3. **`help wanted`**: when the reporter has no plan to send a PR themselves.\n4. **`documentation`** can be combined with `bug` or `enhancement` if the change requires both code and doc updates.\n5. **Never apply on creation**: `duplicate`, `invalid`, `wontfix`, `sync-conflict`. These are triage / automation labels.\n\n## CLI form\n\n```bash\ngh issue create --label \"bug,help wanted\" ...\n```\n\nMultiple labels are comma-separated (no space after the comma).\n\n<!-- File: .claude/skills/issue-create/SKILL.md (Tokens: ~1771 | Category: anthropic-skill) -->\n---\nname: issue-create\ndescription: >-\n  Interview the user to gather all required context, then open a high-quality GitHub issue (`gh issue create`) on the codex-proxy repo with the right template, labels, and structured body.\n  TRIGGER when: user says \"open an issue\", \"file an issue\", \"create issue\", \"report a bug\", \"feature request\", \"提个 issue\", \"报 bug\", \"提需求\".\n  DO NOT TRIGGER when: user wants to view, search, comment on, or close existing issues (use `gh issue list/view/comment/close` directly); user is writing a PR description (use `pr-push`).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Write\"\n---\n\n# Issue Create\n\nGather complete context through a structured interview, then file a well-formed issue. The interview is a hard gate — vague issues waste maintainer time.\n\n## Overview\n\nMost \"I have a bug\" or \"I want a feature\" reports are missing the information a maintainer needs to act. This skill runs a four-phase interview, fills the appropriate template, applies the right labels, and only then calls `gh issue create`. The user sees and approves the rendered body before submission.\n\n## When to Use\n\n- A user wants to file a new issue on the codex-proxy repository.\n- A user describes a bug or feature in conversation and asks \"should we file an issue?\"\n\n## Important Rules\n\n1. **The interview is not optional.** Do NOT call `gh issue create` until all required fields for the chosen type are collected and the user has explicitly approved the rendered body.\n2. **Never invent reproduction steps, version numbers, log output, or behavior.** If the user did not provide it, ask. If they cannot provide it, write \"not provided\" in the field, do not fabricate.\n3. **Show the full body before submitting.** The user must explicitly say \"submit\" / \"looks good\" / equivalent. \"Yes\" without seeing the body is not enough — show it first.\n4. **Apply only labels from the project's existing label set.** Read `references/labels.md` for the catalog. Do not invent new labels.\n5. **Strip secrets.** If the user pastes logs, headers, or config that contain tokens, cookies, OAuth state, API keys, or account IDs, redact them before they enter the issue body. Replace with `<redacted>`.\n6. **One issue per scope.** If the user describes two unrelated problems, file two issues. Ask before splitting.\n\n## Key Workflows\n\n### Phase 1: Type classification\n\n**Goal:** Pick the right template and label.\n\nAsk the user (one consolidated question):\n\n> What type of issue is this?\n>   1. **Bug** — something is broken or behaves incorrectly\n>   2. **Feature request** — propose new functionality\n>   3. **Question** — usage / configuration / \"is this expected?\"\n>   4. **Performance** — measurable regression or slowness\n>   5. **Documentation** — docs are wrong, missing, or unclear\n\nRead the type spec:\n```\nRead: .claude/skills/issue-create/references/issue-types.md\n```\n\nMap answer to template path:\n\n| Type | Template asset | Default label |\n|---|---|---|\n| Bug | `assets/bug-report.md` | `bug` |\n| Feature request | `assets/feature-request.md` | `enhancement` |\n| Question | `assets/question.md` | `question` |\n| Performance | `assets/perf-report.md` | `bug` |\n| Documentation | `assets/feature-request.md` (with docs framing) | `documentation` |\n\nDo **NOT** proceed to Phase 2 until the type is confirmed.\n\n### Phase 2: Required-field interview\n\n**Goal:** Collect every field the chosen template requires.\n\nRead `references/issue-types.md` to see the required-field table for the chosen type. Ask for missing fields in **one consolidated message**, not one at a time. Group related fields together.\n\n**For bugs**, the required fields are:\n- One-line summary\n- Expected behavior\n- Actual behavior\n- Reproduction steps (numbered)\n- Codex-proxy version (`npm pkg get version` or app About dialog)\n- Deployment mode (Electron app / Docker / `npm start` / dev)\n- Relevant log lines (redact secrets)\n- Frequency (always / intermittent / once)\n\n**For feature requests**, the required fields are:\n- Problem the feature solves (user-facing motivation, not the proposed solution)\n- Proposed solution (high level)\n- Alternatives considered\n- Who benefits (single user / all users / specific deployment mode)\n\n**For questions**:\n- What you tried\n- What you expected\n- What happened\n- Relevant config (redact secrets)\n\n**For performance**:\n- All bug fields, plus:\n- Measured baseline vs current (timings, memory, request count — be specific)\n- Reproduction harness (script, steps, or `tests/bench/`)\n\n**For documentation**:\n- Which doc page / file\n- What is wrong or missing\n- Suggested fix (if any)\n\nIf a field cannot be answered, the user must explicitly say \"not applicable\" or \"unknown\" — record that verbatim. Do not silently skip.\n\nDo **NOT** proceed to Phase 3 until every required field has either an answer or an explicit \"not applicable\".\n\n### Phase 3: Code & related-context grounding\n\n**Goal:** Help maintainers find the relevant code fast.\n\nAsk the user for:\n- File paths or `file:line` references they suspect are involved (optional but encouraged).\n- Related issues / PRs to link (`Refs #N`, `Related to #N`).\n- Whether they tried searching existing issues (`gh issue list --search \"<keywords>\"`). If they have not and the report sounds like something that might exist, run the search and show top 3 matches before continuing.\n\nIf the user provides no code locations and the bug is concrete, optionally offer:\n> \"Want me to grep for the relevant code so we can include file:line in the issue?\"\n\nDo not grep silently — ask first, and only do it once.\n\n### Phase 4: Render, confirm, submit\n\n**Goal:** Show the final body, get explicit approval, file the issue.\n\n1. Read the chosen template:\n   ```\n   Read: .claude/skills/issue-create/assets/<template>.md\n   ```\n2. Read the labels catalog:\n   ```\n   Read: .claude/skills/issue-create/references/labels.md\n   ```\n3. Fill the template with the collected fields. Strip secrets per Important Rule #5.\n4. Pick labels:\n   - Always include the type label (Phase 1 mapping).\n   - Add `good first issue` only if the user explicitly says it qualifies (small scope, low context required).\n   - Add `help wanted` if the user has no plan to fix it themselves.\n   - Add `documentation` in addition to the type label if docs need updating.\n5. Show the user the complete rendered output:\n   ```\n   Title: <title>\n   Labels: <label1>, <label2>\n   Body:\n   <full body>\n   ```\n6. Ask: \"Ready to submit, or want to adjust anything?\"\n7. Wait for an explicit affirmative. \"Yes\", \"submit\", \"go\", \"looks good\", \"提交\" all qualify. Silence or hedging does not.\n8. Submit:\n   ```bash\n   gh issue create \\\n     --title \"<title>\" \\\n     --label \"<label1>,<label2>\" \\\n     --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n9. Print the issue URL.\n10. **STOP.** Do not assign, do not comment, do not link to projects unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not call `gh issue create` before showing the body for approval.\n- Do not invent reproduction steps when the user gave a vague report — ask.\n- Do not paste raw logs that contain tokens / cookies / OAuth state / account IDs.\n- Do not apply labels outside the existing catalog.\n- Do not file two issues from one report without confirming the split with the user.\n- Do not grep / search the codebase silently to \"fill in\" missing fields — ask first.\n\n<!-- File: .claude/skills/pr-push/assets/pr-body-template.md (Tokens: ~340 | Category: anthropic-skill) -->\n<!--\nPR body template for codex-proxy. The skill fills in the {{placeholders}}\nand removes optional sections that don't apply. Default language follows\nthe repo's dominant language (currently zh-CN for CHANGELOG entries,\nen for code/commits). Pick one and stay consistent within a single PR.\n-->\n\n## Summary\n\n{{One paragraph: WHAT changed and WHY. Reference the user-visible impact.\nIf multiple commits, summarize the branch's intent, not each commit.}}\n\n## Changes\n\n{{Bulleted list mirroring the CHANGELOG entry. Group by area when the PR\ntouches multiple modules. Reference file paths so reviewers can navigate.}}\n\n- {{change 1 — files}}\n- {{change 2 — files}}\n\n## Test Plan\n\n{{List the commands actually run locally. Do not invent results.\nMark checked items with [x], unchecked with [ ].}}\n\n- [ ] `npm test`\n- [ ] `npm run build`\n- [ ] {{any feature-specific manual verification, e.g. \"Verified Dashboard 用量页 cache hit card renders with mock data\"}}\n- [ ] {{`npm run test:real` if the change touches upstream protocol}}\n\n## Notes\n\n{{Optional. Use for any of:\n - Reviewer attention requests (\"please double-check the SSE buffer math in src/...\")\n - Known follow-ups (\"memory entry for new RT format will land in a separate PR\")\n - Migration / config impact (\"operators must add `update.allow_prerelease` if they want beta\")\n - Screenshots for UI changes\nRemove this section if there are no notes.}}\n\n## Linked Issues\n\n{{Closes #N / Refs #N — remove if none.}}\n\n<!-- File: .claude/skills/pr-push/references/changelog-format.md (Tokens: ~633 | Category: anthropic-skill) -->\n# CHANGELOG Format\n\nCodex-proxy follows [Keep a Changelog](https://keepachangelog.com/). Every PR that changes user-visible behavior, public API, configuration, or build/release infrastructure MUST add an entry to `CHANGELOG.md` under `## [Unreleased]`.\n\n## Section Layout\n\n`## [Unreleased]` contains exactly these subsections (in this order, omit empty ones):\n\n```markdown\n## [Unreleased]\n\n### Changed\n\n- ...\n\n### Added\n\n- ...\n\n### Fixed\n\n- ...\n```\n\n| Subsection | Use for |\n|---|---|\n| `### Added` | New features, new endpoints, new config keys, new CLI flags |\n| `### Changed` | Behavior change of existing features, default value changes, signature changes |\n| `### Fixed` | Bug fixes |\n| `### Removed` | Deleted features (rare; gate behind a deprecation cycle first) |\n| `### Deprecated` | Marking something for future removal |\n| `### Security` | Security-relevant fix (CVE, cred leak, etc.) |\n\n## Entry Style\n\n- Use the same language as the existing `[Unreleased]` entries (zh-CN at time of writing). If the file flips to English, follow.\n- Lead with the user-visible impact, then mention the file paths in parentheses for reviewer navigation.\n- Reference issues / PRs with `(#NNN)` inline.\n- Multi-aspect entries get nested bullets.\n\n## Examples (from current `[Unreleased]`)\n\n```markdown\n### Added\n\n- 图像生成请求计数（成功 / 失败分流）：`AccountUsage` 新增 `image_request_count` / `image_request_failed_count`...\n- Dashboard 用量统计新增「缓存命中率」卡片...\n```\n\n```markdown\n### Changed\n\n- `bump-electron-beta.yml` 触发改为定时 cron（每天 04:00 / 12:00 UTC）...\n```\n\n## When NOT to add a CHANGELOG entry\n\nSkip CHANGELOG for commits that are:\n\n- Test-only (`test:` prefix) — no user impact\n- Doc-only edits to internal docs (`CLAUDE.md`, `.claude/`, `docs/dev-notes/`)\n- Pure refactors that change zero observed behavior (`refactor:` prefix with no API surface change)\n- CI-only changes that do not affect built artifacts (`ci:` prefix)\n- Style/formatting (`style:` prefix)\n\nIf unsure, **add the entry**. A redundant entry is cheaper than a missing one.\n\n## Multi-line / multi-bullet entries\n\nUse the existing nested bullet pattern:\n\n```markdown\n- Ollama bridge cleanup (#403 review followups, closes #405 #406 #407):\n  - `src/ollama/bridge.ts` 不再重复实现 `normalizeHostname`...\n  - `proxyOpenAIRequest` 转发头扩展到...\n  - `MAX_SSE_BUFFER` 重命名为 `MAX_SSE_BUFFER_CHARS`...\n```\n\n<!-- File: .claude/skills/pr-push/references/commit-conventions.md (Tokens: ~670 | Category: anthropic-skill) -->\n# Commit Message Conventions\n\nCodex-proxy uses Conventional Commits with a fixed type vocabulary. Several CI workflows pattern-match on the type prefix, so unknown types break automation.\n\n## Format\n\n```\n<type>(<optional scope>): <imperative summary>\n\n<optional body — wrap at ~72 cols, explain WHY>\n\n<optional footer — Closes #N, Refs #N, BREAKING CHANGE: ...>\n```\n\n- Subject is **imperative mood**, lowercase first letter, no trailing period.\n- Subject ≤ 72 chars hard cap.\n- Body explains *why* the change was made, not *what* (the diff shows what).\n\n## Type Vocabulary\n\n| Type | Use for | Triggers beta release? |\n|---|---|---|\n| `feat` | New user-visible feature | yes |\n| `fix` | Bug fix | yes |\n| `perf` | Performance improvement with no behavior change | yes |\n| `refactor` | Code restructuring with no behavior change | no |\n| `docs` | Documentation only | no |\n| `test` | Test-only changes | no |\n| `chore` | Tooling, dependencies, repo housekeeping | no |\n| `ci` | CI/CD configuration | no |\n| `style` | Formatting, whitespace, no logic change | no |\n\nThe \"Triggers beta release?\" column is determined by `bump-electron-beta.yml`'s skip filter: `^(chore|docs|ci|test|refactor|style)`. Note that `fix(ci):` still triggers a beta release because the prefix is `fix`.\n\n## Scope\n\nOptional, but encouraged for clarity. Use the top-level module name:\n\n- `feat(auth): ...`\n- `fix(translation): ...`\n- `refactor(routes): ...`\n- `chore(deps): ...`\n- `ci(release): ...`\n\nSkip the scope when the change spans multiple modules or is genuinely repo-wide.\n\n## Examples\n\nGood:\n\n```\nfeat(auth): persist account-pool RT-only imports across restarts\n```\n\n```\nfix(translation): recover from previous_response_not_found instead of passing it through\n```\n\n```\nrefactor(routes): extract shared proxy-handler from openai/anthropic/gemini handlers\n```\n\nBad — and why:\n\n| Message | Why it fails |\n|---|---|\n| `Update auth.ts` | No type, describes WHAT not WHY |\n| `feat: Added new feature.` | Past tense + capitalized + trailing period |\n| `feature(auth): persist RT` | `feature` is not in the vocabulary, use `feat` |\n| `fix: stuff` | Subject is meaningless |\n| `wip` | No type, no information |\n\n## Multi-line body\n\nUse a HEREDOC to preserve formatting:\n\n```bash\ngit commit -m \"$(cat <<'EOF'\nfix(quota): ignore stale x-codex-* headers after token refresh\n\nThe previous behavior overwrote fresh quota state with cached headers\nfrom the old token, causing accounts to appear over-quota for ~30s\nafter refresh. Now we drop quota updates whose token id does not match\nthe current session.\n\nCloses #418\nEOF\n)\"\n```\n\n<!-- File: .claude/skills/pr-push/references/pr-checklist.md (Tokens: ~647 | Category: anthropic-skill) -->\n# Pre-PR Self-Check\n\nWalk this list before opening the PR. Anything left unchecked needs a written reason in the PR body.\n\n## Branch & target\n\n- [ ] Current branch is NOT `dev`, `master`, or `main`\n- [ ] Branch is rebased on (or fast-forwardable to) `origin/dev`\n- [ ] PR target = `dev`\n\n## Commit hygiene\n\n- [ ] Each commit follows `<type>(<scope>): <summary>` with a vocabulary type (see `commit-conventions.md`)\n- [ ] No commit was created with `--no-verify`\n- [ ] No file added with `git add -f`\n- [ ] No accidental staging of `node_modules/`, `dist/`, `*.log`, `.env*`, `data/`, or other gitignored paths\n- [ ] No secrets in code or commit messages (API keys, tokens, cookies, oauth_state)\n\n## CHANGELOG\n\n- [ ] If the change touches `src/`, `shared/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` → `CHANGELOG.md` `[Unreleased]` has a new entry\n- [ ] Entry placed in correct subsection (Added / Changed / Fixed)\n- [ ] Entry references the issue / PR number when applicable\n\n## Cross-artifact impact\n\nCodex-proxy ships three artifacts: backend (Docker), Electron desktop, web frontend. The pre-push hook will catch most of these, but verify mentally first:\n\n- [ ] If `src/` changed → backend logic still passes `npm test`\n- [ ] If `web/` changed → `npm run build` produces a clean Vite bundle\n- [ ] If `Dockerfile` / `docker-compose*` changed → image still builds\n- [ ] If `packages/electron/**` or `electron-builder.yml` changed → Electron config validates\n- [ ] If `native/**` changed → native addon still builds\n\n## Tests\n\n- [ ] New behavior has new tests (TDD: tests written first when feasible)\n- [ ] All affected `npm test` suites pass locally\n- [ ] No `*.skip` left behind unless explicitly justified in the PR body\n\n## TypeScript\n\n- [ ] No `any`, `as any`, `: any`, or `<any>` in new code (use `unknown`, generics, or specific types)\n- [ ] No `@ts-ignore` / `@ts-expect-error` without an inline explanation comment\n\n## Real-upstream changes\n\n- [ ] If the change touches the upstream protocol (translation/, proxy/, auth/), `npm run test:real` was attempted at least once\n\n## Documentation\n\n- [ ] Public-facing config/flag changes are reflected in `config/default.yaml` comments and `CLAUDE.md` if relevant\n- [ ] No internal personal notes leaked into committed files\n\n## After push (do NOT do these in this skill)\n\n- [ ] Wait for CI green before requesting review\n- [ ] Merge is a separate, explicit decision — never auto-merge from this skill\n\n<!-- File: .claude/skills/pr-push/SKILL.md (Tokens: ~2347 | Category: anthropic-skill) -->\n---\nname: pr-push\ndescription: >-\n  Package the current working changes into a standards-compliant codex-proxy pull request:\n  branch hygiene, commit message linting, CHANGELOG prompt, conventional commit, push, and `gh pr create` against the `dev` branch.\n  TRIGGER when: user asks to \"push a PR\", \"open a PR\", \"create PR\", \"ship this\", \"推 PR\", \"开 PR\", \"提交 PR\".\n  DO NOT TRIGGER when: user only wants to commit without pushing; user explicitly wants to push directly to master/main; user wants to merge, rebase, or close an existing PR (use `gh pr merge` / `gh pr close` directly).\nallowed-tools:\n  - \"Bash\"\n  - \"Read\"\n  - \"Edit\"\n  - \"Write\"\n  - \"Grep\"\n---\n\n# PR Push\n\nTurn the current working tree into a clean PR targeting `dev`. This skill enforces codex-proxy's contribution rules so community maintainers do not have to memorize them.\n\n## Overview\n\nCodex-proxy uses a `dev` → `master` promotion flow with strict commit conventions, CHANGELOG discipline, and a pre-push validation hook. This skill walks the maintainer through an interview, makes the commit, runs the push (letting the hook gate quality), and opens the PR. It explicitly stops before merge — review and merge are separate human decisions.\n\n## When to Use\n\n- A maintainer has finished a unit of work in their working tree and wants it on `dev`.\n- A maintainer asks to \"open a PR\" or equivalent and the working tree has changes (staged, unstaged, or untracked).\n\n## Important Rules\n\n1. **Target branch is always `dev`.** Never open a PR against `master` or `main` unless the user explicitly states \"target master\" with a written reason. The `master` branch is fast-forwarded by the `promote-dev-to-master.yml` workflow — manual PRs to `master` break that contract.\n2. **Never commit on `dev`, `master`, or `main` directly.** If `git branch --show-current` is one of these, stop and ask the user to name a feature branch (`git switch -c <name>`).\n3. **Never use `git add -A`, `git add .`, or `git add -f`.** Stage files by explicit path. `-f` overrides `.gitignore` and has been the cause of secret leaks elsewhere.\n4. **Never pass `--no-verify` to `git commit` or `git push`.** The hook is the gate. If it fails, fix the underlying issue, do not bypass.\n5. **Stop after `gh pr create`.** Do not merge, do not approve, do not enable auto-merge. Pushing a PR and merging a PR are two human decisions.\n6. **CHANGELOG gate.** If any file under `src/`, `web/`, `packages/`, `native/`, `config/`, or `.github/workflows/` changed, `CHANGELOG.md`'s `[Unreleased]` section MUST have a new entry covering the change before the commit is created.\n7. **Commit message format is fixed:** `<type>(<optional-scope>): <imperative summary>`. The type set is enumerated in `references/commit-conventions.md`.\n\n## Key Workflows\n\n### Phase 1: Discovery (interview, do not touch the repo yet)\n\n**Goal:** Understand what is being shipped before any git operation.\n\nRun these read-only commands in parallel and summarize results back to the user:\n\n```\ngit branch --show-current\ngit status --short\ngit diff --stat\ngit log --oneline -10\n```\n\nThen read the conventions:\n```\nRead: .claude/skills/pr-push/references/commit-conventions.md\nRead: .claude/skills/pr-push/references/changelog-format.md\nRead: .claude/skills/pr-push/references/pr-checklist.md\n```\n\nAsk the user (in one consolidated message) for any field that cannot be inferred:\n\n- **Commit type** (feat / fix / refactor / docs / test / chore / perf / ci) — propose one based on the diff, ask for confirmation.\n- **One-line summary** (imperative, lowercase, no trailing period) — propose one based on the diff.\n- **PR target** — default `dev`. Confirm only if the user previously asked to deviate.\n- **CHANGELOG entry** — if the gate in Important Rules #6 applies and `CHANGELOG.md` `[Unreleased]` has no matching entry, ask the user to dictate one (or offer to draft one for review). Do not invent silently.\n- **Memory / docs touch** — if the change touches public protocol, request flow, auth lifecycle, or release infra, ask whether `CLAUDE.md` needs updating in the same PR.\n\nDo **NOT** proceed to Phase 2 until the user has explicitly confirmed (a) commit type, (b) summary, (c) CHANGELOG status, (d) target = `dev`.\n\n### Phase 2: Branch hygiene\n\n**Goal:** Make sure the commit lands on a feature branch, not on `dev`/`master`.\n\n1. Check `git branch --show-current`.\n2. If the current branch is `dev`, `master`, or `main`:\n   - Stop. Ask the user to provide a feature branch name (suggest one derived from the commit summary, kebab-case, ≤40 chars).\n   - Run `git switch -c <name>`. Do not auto-pick a name without confirmation.\n3. If the current branch is a feature branch but is not based on up-to-date `origin/dev`:\n   - Run `git fetch origin dev`.\n   - If `git merge-base --is-ancestor origin/dev HEAD` is false (branch is behind), warn the user and ask whether to `git rebase origin/dev` before continuing. Do not rebase silently.\n\n### Phase 3: Stage + commit\n\n**Goal:** Produce one well-formed commit.\n\n1. List the files the user wants in this commit. If they didn't say, propose the list from `git status --short` and confirm.\n2. Run `git add <file1> <file2> ...` with explicit paths. Never `-A`, `.`, or `-f`.\n3. If CHANGELOG was updated as part of Phase 1, include `CHANGELOG.md` in the staged set.\n4. Build the commit message:\n   - First line: `<type>(<scope>): <summary>` — scope is optional, omit parentheses if no scope.\n   - Body (optional): wrap at ~72 cols, explain *why*, reference issues with `Closes #N` / `Refs #N` if applicable.\n5. Commit with a HEREDOC (preserves formatting):\n   ```bash\n   git commit -m \"$(cat <<'EOF'\n   <type>(<scope>): <summary>\n\n   <optional body>\n   EOF\n   )\"\n   ```\n6. If the commit fails because of a pre-commit hook, fix the reported issue and create a NEW commit (do not `--amend`). Re-run the same command after fixes.\n\n### Phase 4: Push\n\n**Goal:** Get the branch to `origin` so a PR can be opened.\n\n1. Confirm the user wants to push (a single short \"ready to push?\" — they may have wanted to inspect the commit first).\n2. **Hook presence check.** The repo's pre-push gate lives at `.claude/hooks/pre-push-validate.sh`, which is gitignored — fresh clones do **not** have it. Run `test -x .claude/hooks/pre-push-validate.sh`:\n   - **Hook present** → push normally; the hook will run.\n   - **Hook missing** → warn the user that no pre-push gate is installed, then run the equivalent checks inline based on what the diff touched, before pushing:\n     | Diff touches | Run |\n     |---|---|\n     | `src/**` or `tests/**` | `npm test` and `npx tsc --noEmit` |\n     | `web/**` | `npm run build` |\n     | `Dockerfile`, `docker-compose*` | `docker build .` (or note user must verify) |\n     | `packages/electron/**`, `electron-builder.yml` | `npm run -w packages/electron build` |\n     | `native/**` | `npm run -w native build` |\n     Any failure aborts the push — fix and re-run.\n3. Run `git push -u origin HEAD`.\n4. If the push is blocked by the hook:\n   - Read the hook output verbatim back to the user.\n   - The hook validates the build targets affected by the diff (test, tsc, web build, Dockerfile lint, Electron config, native addon). Identify which target failed and propose a fix.\n   - **Never retry with `--no-verify`.** Re-run the offending check locally, fix the root cause, amend the commit only if the user authorizes it, otherwise add a fix-up commit.\n\n### Phase 5: Open the PR\n\n**Goal:** Create a PR against `dev` with a body that future reviewers can read cold.\n\n1. Read the PR body template:\n   ```\n   Read: .claude/skills/pr-push/assets/pr-body-template.md\n   ```\n2. Determine PR title:\n   - If the branch has a single commit, reuse the commit subject.\n   - If multiple commits, propose a title that summarizes the branch's intent and confirm with user.\n   - Title MUST start with a conventional type, MUST be ≤72 chars.\n3. Fill the body sections (Summary / Test Plan / Notes). Source content from:\n   - `git log <base>..HEAD` for the change list.\n   - The CHANGELOG entry the user wrote.\n   - Test commands actually run locally (do not invent test results).\n4. Show the rendered title + body to the user. **Wait for explicit \"looks good\" before invoking `gh`.**\n5. Create the PR:\n   ```bash\n   gh pr create --base dev --title \"<title>\" --body \"$(cat <<'EOF'\n   <body>\n   EOF\n   )\"\n   ```\n6. Print the PR URL.\n7. **STOP.** Do not run `gh pr merge`, `gh pr review --approve`, `gh pr edit --add-label`, or `--auto-merge` unless the user issues a separate, explicit command.\n\n## Common Pitfalls\n\n- Do not assume the user wants every modified file in the PR — ask.\n- Do not auto-write the CHANGELOG entry without showing it for approval first.\n- Do not retry a failing pre-push hook with `--no-verify`.\n- Do not open the PR against `master` even if the user is on a branch named `master-fix-X` — branch name does not imply target.\n- Do not silently rebase. If the branch needs rebase against `origin/dev`, ask first.\n- Do not chain `gh pr create` with `gh pr merge`. Two separate decisions.\n\n<!-- File: packages/npm/README.md (Tokens: ~584 | Category: plugin-manifest) -->\n# @icebear0828/codex-proxy\n\nOpenAI-compatible proxy for the ChatGPT Codex Responses API, with a web dashboard, a multi-account key pool and an Ollama-compatible bridge. This is the full application — dashboard, account management and the Ollama bridge all work the same as the desktop and Docker versions.\n\n## Install\n\nRequires Node.js 22.13+ (uses the built-in `node:sqlite`).\n\nThis package is published to GitHub Packages, not to the public npmjs registry. Installing it from GitHub Packages needs an npm auth token with `read:packages`:\n\n```ini\n@icebear0828:registry=https://npm.pkg.github.com\n//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}\n```\n\n```bash\nnpm install -g @icebear0828/codex-proxy\n```\n\nNo-auth alternative: download `codex-proxy-npm.zip` from the [latest release](https://github.com/icebear0828/codex-proxy/releases/latest/download/codex-proxy-npm.zip), extract it and run `node install.mjs` inside the extracted directory.\n\n## Run\n\n```bash\ncodex-proxy            # starts the server and opens the dashboard\ncodex-proxy --mode=server   # headless server only\ncodex-proxy --mode=browser  # force the system browser\ncodex-proxy --help          # all options\n```\n\nOn first start the dashboard opens at `http://127.0.0.1:8080` (port configurable via `--port` or `PORT`). On Windows the dashboard opens in your system browser; the desktop app and the Lite zip ship a native WebView2 host, which the npm package does not include.\n\nRuntime data (accounts, config, usage history) is stored in the per-user data directory (`%APPDATA%\\@codex-proxy\\electron\\data` on Windows, `~/.config/@codex-proxy/electron/data` on Linux, `~/Library/Application Support/@codex-proxy/electron/data` on macOS), so it survives package updates. Set `CODEX_PROXY_DATA_DIR` or pass `--portable` to relocate it. Platform-specific TLS addons are installed automatically for your OS/architecture; binaries for other platforms are never downloaded.\n\n## Links\n\n- [GitHub repository](https://github.com/icebear0828/codex-proxy)\n- [Documentation & screenshots](https://github.com/icebear0828/codex-proxy#readme)\n- Desktop installers, the portable zip and Docker images are published on the [releases page](https://github.com/icebear0828/codex-proxy/releases).\n\n## License\n\nNon-commercial licence — see [LICENCE](https://github.com/icebear0828/codex-proxy/blob/dev/LICENCE).\n</yakaai_skills>"}