hack/tools/scripts/llm-key-hunter/results/_cache/content/ahoo-wang_godex.json

{"repo": "ahoo-wang/godex", "files": {"README.md": {"9efb5d28b803166fc52e46da8d469512befd054b": {"t": 1785595198.5481348, "n": 12669, "h": "26353555bff64e0a", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n[**English Documentation**](https://godex.ahoo.me/) · [**中文文档**](https://godex.ahoo.me/zh/)\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Hybrid web search support with provider-native declarations for Zhipu/Xiaomi and GodeX-managed hosted search through the Zhipu Web Search API.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | GodeX Input | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | text | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | text | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | boolean | text, image, video | auto, none, required, function | text, json_object | ✅ | `MiniMax-M3` |\n| Zhipu    | boolean | text | auto, none | text, json_object | ✅ | `glm-5.2` |\n\n## Architecture\n\n![GodeX architecture](docs/assets/godex-architecture-branded.png)\n\n## Component Interaction\n\n![GodeX component interaction](docs/assets/godex-component-interaction-branded.png)\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    #\n    # 这些 alias 是 GodeX routing policy，不代表与 OpenAI 原模型能力等价。\n    # 依据优先级：公开 benchmark > 官方模型定位 > Provider 产品说明。\n    # -------------------------------------------------------------------------\n\n    # Codex 默认主力：复杂编码 / computer use / research workflows\n    # 依据：DeepSeek V4-Pro 在 SWE / Terminal / Codeforces / GDPval-AA 上公开成绩强。\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n\n    # Codex 旗舰：coding + reasoning + tool use + agentic workflows\n    # 依据：DeepSeek V4-Pro 有更完整的公开 coding/agentic benchmark 覆盖。\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n\n    # Codex mini：subagents\n    gpt-5.4-mini: \"zhipu/glm-5.1\"\n\n    # Codex 编码专用：复杂软件工程\n    # 依据：DeepSeek V4-Pro 的 SWE Verified / SWE Pro / Terminal Bench 表现。\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n\n    # Codex spark：近实时编码迭代\n    gpt-5.3-codex-spark: \"zhipu/glm-5.1\"\n\n    # 上一代通用 coding / agentic fallback\n    # 严谨起见仍走 DeepSeek；不强行映射到 Zhipu。\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # -------------------------------------------------------------------------\n    # Provider native models\n    # -------------------------------------------------------------------------\n\n    deepseek-v4-pro: \"deepseek/deepseek-v4-pro\"\n    deepseek-v4-flash: \"deepseek/deepseek-v4-flash\"\n\n    mimo-v2.5-pro: \"xiaomi/mimo-v2.5-pro\"\n    mimo-v2.5: \"xiaomi/mimo-v2.5\"\n\n    glm-5.1: \"zhipu/glm-5.1\"\n    glm-5-turbo: \"zhipu/glm-5-turbo\"\n    glm-4.7: \"zhipu/glm-4.7\"\n    glm-4.5-air: \"zhipu/glm-4.5-air\"\n\n    MiniMax-M3: \"minimax/MiniMax-M3\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nweb_search:\n  enabled: true\n  mode: auto\n  provider: zhipu\n  on_unavailable: client_tool_call\n  max_iterations: 2\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n\n## Codex Integration\n\nConnect the Codex desktop app to GodeX by adding a custom provider in `~/.codex/config.toml`:\n\n```toml\nmodel = \"gpt-5.5\"\nmodel_provider = \"godex\"\n\n[model_providers.godex]\nname = \"GodeX\"\nbase_url = \"http://127.0.0.1:5678/v1\"\nwire_api = \"responses\"\nrequires_openai_auth = false\nsupports_websockets = false\n```\n\nModel aliases (`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, etc.) are resolved by GodeX using the `models.aliases` map in `godex.yaml` — Codex itself only needs the alias name.\n\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata and final patched request payload summaries\n- Provider request lifecycle events without duplicating full request bodies\n- Sync provider response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes` for trace rows that carry payloads. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "65e82bfe593cda21c1ea3f408546df5519d939a1": {"t": 1785746651.2833636, "n": 12669, "h": "26353555bff64e0a", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n[**English Documentation**](https://godex.ahoo.me/) · [**中文文档**](https://godex.ahoo.me/zh/)\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Hybrid web search support with provider-native declarations for Zhipu/Xiaomi and GodeX-managed hosted search through the Zhipu Web Search API.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | GodeX Input | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | text | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | text | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | boolean | text, image, video | auto, none, required, function | text, json_object | ✅ | `MiniMax-M3` |\n| Zhipu    | boolean | text | auto, none | text, json_object | ✅ | `glm-5.2` |\n\n## Architecture\n\n![GodeX architecture](docs/assets/godex-architecture-branded.png)\n\n## Component Interaction\n\n![GodeX component interaction](docs/assets/godex-component-interaction-branded.png)\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    #\n    # 这些 alias 是 GodeX routing policy，不代表与 OpenAI 原模型能力等价。\n    # 依据优先级：公开 benchmark > 官方模型定位 > Provider 产品说明。\n    # -------------------------------------------------------------------------\n\n    # Codex 默认主力：复杂编码 / computer use / research workflows\n    # 依据：DeepSeek V4-Pro 在 SWE / Terminal / Codeforces / GDPval-AA 上公开成绩强。\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n\n    # Codex 旗舰：coding + reasoning + tool use + agentic workflows\n    # 依据：DeepSeek V4-Pro 有更完整的公开 coding/agentic benchmark 覆盖。\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n\n    # Codex mini：subagents\n    gpt-5.4-mini: \"zhipu/glm-5.1\"\n\n    # Codex 编码专用：复杂软件工程\n    # 依据：DeepSeek V4-Pro 的 SWE Verified / SWE Pro / Terminal Bench 表现。\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n\n    # Codex spark：近实时编码迭代\n    gpt-5.3-codex-spark: \"zhipu/glm-5.1\"\n\n    # 上一代通用 coding / agentic fallback\n    # 严谨起见仍走 DeepSeek；不强行映射到 Zhipu。\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # -------------------------------------------------------------------------\n    # Provider native models\n    # -------------------------------------------------------------------------\n\n    deepseek-v4-pro: \"deepseek/deepseek-v4-pro\"\n    deepseek-v4-flash: \"deepseek/deepseek-v4-flash\"\n\n    mimo-v2.5-pro: \"xiaomi/mimo-v2.5-pro\"\n    mimo-v2.5: \"xiaomi/mimo-v2.5\"\n\n    glm-5.1: \"zhipu/glm-5.1\"\n    glm-5-turbo: \"zhipu/glm-5-turbo\"\n    glm-4.7: \"zhipu/glm-4.7\"\n    glm-4.5-air: \"zhipu/glm-4.5-air\"\n\n    MiniMax-M3: \"minimax/MiniMax-M3\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nweb_search:\n  enabled: true\n  mode: auto\n  provider: zhipu\n  on_unavailable: client_tool_call\n  max_iterations: 2\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n\n## Codex Integration\n\nConnect the Codex desktop app to GodeX by adding a custom provider in `~/.codex/config.toml`:\n\n```toml\nmodel = \"gpt-5.5\"\nmodel_provider = \"godex\"\n\n[model_providers.godex]\nname = \"GodeX\"\nbase_url = \"http://127.0.0.1:5678/v1\"\nwire_api = \"responses\"\nrequires_openai_auth = false\nsupports_websockets = false\n```\n\nModel aliases (`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, etc.) are resolved by GodeX using the `models.aliases` map in `godex.yaml` — Codex itself only needs the alias name.\n\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata and final patched request payload summaries\n- Provider request lifecycle events without duplicating full request bodies\n- Sync provider response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes` for trace rows that carry payloads. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "73dc7f9db96e952601047e466be3730d0cc8886c": {"t": 1785748565.482432, "n": 12669, "h": "26353555bff64e0a", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n[**English Documentation**](https://godex.ahoo.me/) · [**中文文档**](https://godex.ahoo.me/zh/)\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Hybrid web search support with provider-native declarations for Zhipu/Xiaomi and GodeX-managed hosted search through the Zhipu Web Search API.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | GodeX Input | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | text | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | text | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | boolean | text, image, video | auto, none, required, function | text, json_object | ✅ | `MiniMax-M3` |\n| Zhipu    | boolean | text | auto, none | text, json_object | ✅ | `glm-5.2` |\n\n## Architecture\n\n![GodeX architecture](docs/assets/godex-architecture-branded.png)\n\n## Component Interaction\n\n![GodeX component interaction](docs/assets/godex-component-interaction-branded.png)\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    #\n    # 这些 alias 是 GodeX routing policy，不代表与 OpenAI 原模型能力等价。\n    # 依据优先级：公开 benchmark > 官方模型定位 > Provider 产品说明。\n    # -------------------------------------------------------------------------\n\n    # Codex 默认主力：复杂编码 / computer use / research workflows\n    # 依据：DeepSeek V4-Pro 在 SWE / Terminal / Codeforces / GDPval-AA 上公开成绩强。\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n\n    # Codex 旗舰：coding + reasoning + tool use + agentic workflows\n    # 依据：DeepSeek V4-Pro 有更完整的公开 coding/agentic benchmark 覆盖。\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n\n    # Codex mini：subagents\n    gpt-5.4-mini: \"zhipu/glm-5.1\"\n\n    # Codex 编码专用：复杂软件工程\n    # 依据：DeepSeek V4-Pro 的 SWE Verified / SWE Pro / Terminal Bench 表现。\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n\n    # Codex spark：近实时编码迭代\n    gpt-5.3-codex-spark: \"zhipu/glm-5.1\"\n\n    # 上一代通用 coding / agentic fallback\n    # 严谨起见仍走 DeepSeek；不强行映射到 Zhipu。\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # -------------------------------------------------------------------------\n    # Provider native models\n    # -------------------------------------------------------------------------\n\n    deepseek-v4-pro: \"deepseek/deepseek-v4-pro\"\n    deepseek-v4-flash: \"deepseek/deepseek-v4-flash\"\n\n    mimo-v2.5-pro: \"xiaomi/mimo-v2.5-pro\"\n    mimo-v2.5: \"xiaomi/mimo-v2.5\"\n\n    glm-5.1: \"zhipu/glm-5.1\"\n    glm-5-turbo: \"zhipu/glm-5-turbo\"\n    glm-4.7: \"zhipu/glm-4.7\"\n    glm-4.5-air: \"zhipu/glm-4.5-air\"\n\n    MiniMax-M3: \"minimax/MiniMax-M3\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nweb_search:\n  enabled: true\n  mode: auto\n  provider: zhipu\n  on_unavailable: client_tool_call\n  max_iterations: 2\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n\n## Codex Integration\n\nConnect the Codex desktop app to GodeX by adding a custom provider in `~/.codex/config.toml`:\n\n```toml\nmodel = \"gpt-5.5\"\nmodel_provider = \"godex\"\n\n[model_providers.godex]\nname = \"GodeX\"\nbase_url = \"http://127.0.0.1:5678/v1\"\nwire_api = \"responses\"\nrequires_openai_auth = false\nsupports_websockets = false\n```\n\nModel aliases (`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, etc.) are resolved by GodeX using the `models.aliases` map in `godex.yaml` — Codex itself only needs the alias name.\n\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata and final patched request payload summaries\n- Provider request lifecycle events without duplicating full request bodies\n- Sync provider response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes` for trace rows that carry payloads. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "ee1306ba5f586c26a0f546ced1c67fbb7509e6ff": {"t": 1785748566.5837085, "n": 12409, "h": "1446fc061e5e0042", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n[**English Documentation**](https://godex.ahoo.me/) · [**中文文档**](https://godex.ahoo.me/zh/)\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | GodeX Input | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | text | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | text | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | boolean | text, image, video | auto, none, required, function | text, json_object | ✅ | `MiniMax-M3` |\n| Zhipu    | boolean | text | auto, none | text, json_object | ✅ | `glm-5.2` |\n\n## Architecture\n\n![GodeX architecture](docs/assets/godex-architecture-branded.png)\n\n## Component Interaction\n\n![GodeX component interaction](docs/assets/godex-component-interaction-branded.png)\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    #\n    # 这些 alias 是 GodeX routing policy，不代表与 OpenAI 原模型能力等价。\n    # 依据优先级：公开 benchmark > 官方模型定位 > Provider 产品说明。\n    # -------------------------------------------------------------------------\n\n    # Codex 默认主力：复杂编码 / computer use / research workflows\n    # 依据：DeepSeek V4-Pro 在 SWE / Terminal / Codeforces / GDPval-AA 上公开成绩强。\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n\n    # Codex 旗舰：coding + reasoning + tool use + agentic workflows\n    # 依据：DeepSeek V4-Pro 有更完整的公开 coding/agentic benchmark 覆盖。\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n\n    # Codex mini：subagents\n    gpt-5.4-mini: \"zhipu/glm-5.1\"\n\n    # Codex 编码专用：复杂软件工程\n    # 依据：DeepSeek V4-Pro 的 SWE Verified / SWE Pro / Terminal Bench 表现。\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n\n    # Codex spark：近实时编码迭代\n    gpt-5.3-codex-spark: \"zhipu/glm-5.1\"\n\n    # 上一代通用 coding / agentic fallback\n    # 严谨起见仍走 DeepSeek；不强行映射到 Zhipu。\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # -------------------------------------------------------------------------\n    # Provider native models\n    # -------------------------------------------------------------------------\n\n    deepseek-v4-pro: \"deepseek/deepseek-v4-pro\"\n    deepseek-v4-flash: \"deepseek/deepseek-v4-flash\"\n\n    mimo-v2.5-pro: \"xiaomi/mimo-v2.5-pro\"\n    mimo-v2.5: \"xiaomi/mimo-v2.5\"\n\n    glm-5.1: \"zhipu/glm-5.1\"\n    glm-5-turbo: \"zhipu/glm-5-turbo\"\n    glm-4.7: \"zhipu/glm-4.7\"\n    glm-4.5-air: \"zhipu/glm-4.5-air\"\n\n    MiniMax-M3: \"minimax/MiniMax-M3\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n\n## Codex Integration\n\nConnect the Codex desktop app to GodeX by adding a custom provider in `~/.codex/config.toml`:\n\n```toml\nmodel = \"gpt-5.5\"\nmodel_provider = \"godex\"\n\n[model_providers.godex]\nname = \"GodeX\"\nbase_url = \"http://127.0.0.1:5678/v1\"\nwire_api = \"responses\"\nrequires_openai_auth = false\nsupports_websockets = false\n```\n\nModel aliases (`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, etc.) are resolved by GodeX using the `models.aliases` map in `godex.yaml` — Codex itself only needs the alias name.\n\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata and final patched request payload summaries\n- Provider request lifecycle events without duplicating full request bodies\n- Sync provider response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes` for trace rows that carry payloads. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "1e5b993622690d731ddb202f06d5436796fbe69f": {"t": 1785748567.7279484, "n": 12409, "h": "c2f0b6c57fb19839", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n[**English Documentation**](https://godex.ahoo.me/) · [**中文文档**](https://godex.ahoo.me/zh/)\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | GodeX Input | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | text | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | text | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | boolean | text, image, video | auto, none, required, function | text, json_object | ✅ | `MiniMax-M3` |\n| Zhipu    | boolean | text | auto, none | text, json_object | ✅ | `glm-5.1` |\n\n## Architecture\n\n![GodeX architecture](docs/assets/godex-architecture-branded.png)\n\n## Component Interaction\n\n![GodeX component interaction](docs/assets/godex-component-interaction-branded.png)\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    #\n    # 这些 alias 是 GodeX routing policy，不代表与 OpenAI 原模型能力等价。\n    # 依据优先级：公开 benchmark > 官方模型定位 > Provider 产品说明。\n    # -------------------------------------------------------------------------\n\n    # Codex 默认主力：复杂编码 / computer use / research workflows\n    # 依据：DeepSeek V4-Pro 在 SWE / Terminal / Codeforces / GDPval-AA 上公开成绩强。\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n\n    # Codex 旗舰：coding + reasoning + tool use + agentic workflows\n    # 依据：DeepSeek V4-Pro 有更完整的公开 coding/agentic benchmark 覆盖。\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n\n    # Codex mini：subagents\n    gpt-5.4-mini: \"zhipu/glm-5.1\"\n\n    # Codex 编码专用：复杂软件工程\n    # 依据：DeepSeek V4-Pro 的 SWE Verified / SWE Pro / Terminal Bench 表现。\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n\n    # Codex spark：近实时编码迭代\n    gpt-5.3-codex-spark: \"zhipu/glm-5.1\"\n\n    # 上一代通用 coding / agentic fallback\n    # 严谨起见仍走 DeepSeek；不强行映射到 Zhipu。\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # -------------------------------------------------------------------------\n    # Provider native models\n    # -------------------------------------------------------------------------\n\n    deepseek-v4-pro: \"deepseek/deepseek-v4-pro\"\n    deepseek-v4-flash: \"deepseek/deepseek-v4-flash\"\n\n    mimo-v2.5-pro: \"xiaomi/mimo-v2.5-pro\"\n    mimo-v2.5: \"xiaomi/mimo-v2.5\"\n\n    glm-5.1: \"zhipu/glm-5.1\"\n    glm-5-turbo: \"zhipu/glm-5-turbo\"\n    glm-4.7: \"zhipu/glm-4.7\"\n    glm-4.5-air: \"zhipu/glm-4.5-air\"\n\n    MiniMax-M3: \"minimax/MiniMax-M3\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n\n## Codex Integration\n\nConnect the Codex desktop app to GodeX by adding a custom provider in `~/.codex/config.toml`:\n\n```toml\nmodel = \"gpt-5.5\"\nmodel_provider = \"godex\"\n\n[model_providers.godex]\nname = \"GodeX\"\nbase_url = \"http://127.0.0.1:5678/v1\"\nwire_api = \"responses\"\nrequires_openai_auth = false\nsupports_websockets = false\n```\n\nModel aliases (`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, etc.) are resolved by GodeX using the `models.aliases` map in `godex.yaml` — Codex itself only needs the alias name.\n\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata and final patched request payload summaries\n- Provider request lifecycle events without duplicating full request bodies\n- Sync provider response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes` for trace rows that carry payloads. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "b5919b8cc0b14163d1e96f13664f0c5ff7da294c": {"t": 1785748568.849063, "n": 12404, "h": "da60e24d89395d19", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n[**English Documentation**](https://godex.ahoo.me/) · [**中文文档**](https://godex.ahoo.me/zh/)\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | none  | auto, none, required, function | text, json_object | ✅ | `MiniMax-M2.7` |\n| Zhipu    | boolean | auto, none | text, json_object | ✅ | `glm-5.1` |\n\n## Architecture\n\n![GodeX architecture](docs/assets/godex-architecture-branded.png)\n\n## Component Interaction\n\n![GodeX component interaction](docs/assets/godex-component-interaction-branded.png)\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    #\n    # 这些 alias 是 GodeX routing policy，不代表与 OpenAI 原模型能力等价。\n    # 依据优先级：公开 benchmark > 官方模型定位 > Provider 产品说明。\n    # -------------------------------------------------------------------------\n\n    # Codex 默认主力：复杂编码 / computer use / research workflows\n    # 依据：DeepSeek V4-Pro 在 SWE / Terminal / Codeforces / GDPval-AA 上公开成绩强。\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n\n    # Codex 旗舰：coding + reasoning + tool use + agentic workflows\n    # 依据：DeepSeek V4-Pro 有更完整的公开 coding/agentic benchmark 覆盖。\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n\n    # Codex mini：subagents\n    gpt-5.4-mini: \"zhipu/glm-5.1\"\n\n    # Codex 编码专用：复杂软件工程\n    # 依据：DeepSeek V4-Pro 的 SWE Verified / SWE Pro / Terminal Bench 表现。\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n\n    # Codex spark：近实时编码迭代\n    gpt-5.3-codex-spark: \"zhipu/glm-5.1\"\n\n    # 上一代通用 coding / agentic fallback\n    # 严谨起见仍走 DeepSeek；不强行映射到 Zhipu。\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # -------------------------------------------------------------------------\n    # Provider native models\n    # -------------------------------------------------------------------------\n\n    deepseek-v4-pro: \"deepseek/deepseek-v4-pro\"\n    deepseek-v4-flash: \"deepseek/deepseek-v4-flash\"\n\n    mimo-v2.5-pro: \"xiaomi/mimo-v2.5-pro\"\n    mimo-v2.5: \"xiaomi/mimo-v2.5\"\n\n    glm-5.1: \"zhipu/glm-5.1\"\n    glm-5-turbo: \"zhipu/glm-5-turbo\"\n    glm-4.7: \"zhipu/glm-4.7\"\n    glm-4.5-air: \"zhipu/glm-4.5-air\"\n\n    MiniMax-M2.7: \"minimax/MiniMax-M2.7\"\n    MiniMax-M2.7-highspeed: \"minimax/MiniMax-M2.7-highspeed\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n\n## Codex Integration\n\nConnect the Codex desktop app to GodeX by adding a custom provider in `~/.codex/config.toml`:\n\n```toml\nmodel = \"gpt-5.5\"\nmodel_provider = \"godex\"\n\n[model_providers.godex]\nname = \"GodeX\"\nbase_url = \"http://127.0.0.1:5678/v1\"\nwire_api = \"responses\"\nrequires_openai_auth = false\nsupports_websockets = false\n```\n\nModel aliases (`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, etc.) are resolved by GodeX using the `models.aliases` map in `godex.yaml` — Codex itself only needs the alias name.\n\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata and final patched request payload summaries\n- Provider request lifecycle events without duplicating full request bodies\n- Sync provider response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes` for trace rows that carry payloads. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "cf99c27bcfe9add2fdf0f24baaf8198375af1014": {"t": 1785748569.9500813, "n": 15738, "h": "ba80dc0b64bf9f5a", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n[**English Documentation**](https://godex.ahoo.me/) · [**中文文档**](https://godex.ahoo.me/zh/)\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | none  | auto, none, required, function | text, json_object | ✅ | `MiniMax-M2.7` |\n| Zhipu    | boolean | auto, none | text, json_object | ✅ | `glm-5.1` |\n\n## Architecture\n\n```mermaid\nflowchart TB\n  Client[\"Client<br>Codex, SDK, CLI, IDE\"] --> Routes[\"Bun server routes<br>/health<br>/v1/models<br>/v1/responses\"]\n  Routes --> Ctx[\"ResponsesContext<br>request id, response id, resolved model,<br>provider, session, diagnostics\"]\n\n  Ctx --> Resolver[\"ModelResolver<br>alias and provider/model selection\"]\n  Ctx --> Session[\"ResponseSessionStore<br>memory or SQLite<br>previous_response_id chains\"]\n  Ctx --> Registrar[\"Registrar<br>built-in ProviderEdge factories\"]\n  Ctx --> Runtime[\"ResponsesBridgeRuntime\"]\n\n  Runtime --> Sync[\"SyncRequestPipeline\"]\n  Runtime --> Stream[\"StreamPipeline\"]\n  Sync --> Exchange[\"ProviderExchange\"]\n  Stream --> Exchange\n\n  Exchange --> Builder[\"bridge/request<br>buildChatCompletionRequest\"]\n  Builder --> Compat[\"bridge/compatibility<br>parameter and response-format decisions\"]\n  Builder --> Tools[\"bridge/tools<br>tool declarations, tool_choice,<br>identity restoration\"]\n  Builder --> Output[\"bridge/output<br>structured-output contract\"]\n\n  Exchange --> Edge[\"ProviderEdge<br>ProviderSpec + hooks\"]\n  Edge --> ClientHttp[\"ChatProviderClient<br>Fetcher HTTP boundary\"]\n  ClientHttp --> Upstream[\"Chat Completions upstream<br>DeepSeek, Xiaomi, MiniMax, Zhipu, custom\"]\n\n  Upstream --> SyncRecon[\"bridge/response<br>reconstructResponseObject\"]\n  Upstream --> StreamRecon[\"bridge/stream<br>ResponseStreamStateMachine\"]\n  SyncRecon --> ResponseJson[\"ResponseObject JSON\"]\n  StreamRecon --> StreamTransforms[\"stream transforms<br>validate, trace, log, persist, diagnostics\"]\n  StreamTransforms --> Sse[\"Responses SSE\"]\n\n  Ctx --> Trace[\"trace recorder<br>request, usage, event, error rows\"]\n  Ctx --> Logger[\"structured logger\"]\n```\n\n## Component Interaction\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor Client\n  participant Server as /v1/responses route\n  participant Context as ResponsesContext factory\n  participant Resolver as ModelResolver\n  participant Store as ResponseSessionStore\n  participant Registrar\n  participant Runtime as ResponsesBridgeRuntime\n  participant Exchange as ProviderExchange\n  participant Bridge as bridge/request\n  participant Provider as ProviderEdge\n  participant Upstream as Chat Completions API\n\n  Client->>Server: POST /v1/responses\n  Server->>Server: parse and validate JSON envelope\n  Server->>Context: create(app, body)\n  Context->>Resolver: resolve(body.model)\n  Resolver-->>Context: provider + upstream model\n  opt previous_response_id\n    Context->>Store: resolveChain(previous_response_id)\n    Store-->>Context: ordered session snapshot\n  end\n  Context->>Registrar: resolve(provider)\n  Registrar-->>Context: ProviderEdge\n  Server->>Runtime: request(ctx) or stream(ctx)\n  Runtime->>Exchange: build and send provider request\n  Exchange->>Bridge: buildChatCompletionRequest(ctx)\n  Bridge-->>Exchange: chat request + compatibility/tool/output plans\n  Exchange->>Provider: request(body) or stream(body)\n  Provider->>Upstream: POST /chat/completions\n  Upstream-->>Provider: JSON response or SSE chunks\n  alt sync\n    Provider-->>Exchange: provider response\n    Exchange-->>Runtime: provider response + plans\n    Runtime->>Store: save completed response unless store=false\n    Runtime-->>Server: ResponseObject\n    Server-->>Client: JSON\n  else stream\n    Provider-->>Exchange: provider SSE stream\n    Exchange-->>Runtime: stream + plans\n    Runtime->>Runtime: bridge deltas, validate output, trace, log, persist\n    Runtime-->>Server: ResponseStreamEvent stream\n    Server-->>Client: text/event-stream\n  end\n```\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    #\n    # 这些 alias 是 GodeX routing policy，不代表与 OpenAI 原模型能力等价。\n    # 依据优先级：公开 benchmark > 官方模型定位 > Provider 产品说明。\n    # -------------------------------------------------------------------------\n\n    # Codex 默认主力：复杂编码 / computer use / research workflows\n    # 依据：DeepSeek V4-Pro 在 SWE / Terminal / Codeforces / GDPval-AA 上公开成绩强。\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n\n    # Codex 旗舰：coding + reasoning + tool use + agentic workflows\n    # 依据：DeepSeek V4-Pro 有更完整的公开 coding/agentic benchmark 覆盖。\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n\n    # Codex mini：subagents\n    gpt-5.4-mini: \"zhipu/glm-5.1\"\n\n    # Codex 编码专用：复杂软件工程\n    # 依据：DeepSeek V4-Pro 的 SWE Verified / SWE Pro / Terminal Bench 表现。\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n\n    # Codex spark：近实时编码迭代\n    gpt-5.3-codex-spark: \"zhipu/glm-5.1\"\n\n    # 上一代通用 coding / agentic fallback\n    # 严谨起见仍走 DeepSeek；不强行映射到 Zhipu。\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # -------------------------------------------------------------------------\n    # Provider native models\n    # -------------------------------------------------------------------------\n\n    deepseek-v4-pro: \"deepseek/deepseek-v4-pro\"\n    deepseek-v4-flash: \"deepseek/deepseek-v4-flash\"\n\n    mimo-v2.5-pro: \"xiaomi/mimo-v2.5-pro\"\n    mimo-v2.5: \"xiaomi/mimo-v2.5\"\n\n    glm-5.1: \"zhipu/glm-5.1\"\n    glm-5-turbo: \"zhipu/glm-5-turbo\"\n    glm-4.7: \"zhipu/glm-4.7\"\n    glm-4.5-air: \"zhipu/glm-4.5-air\"\n\n    MiniMax-M2.7: \"minimax/MiniMax-M2.7\"\n    MiniMax-M2.7-highspeed: \"minimax/MiniMax-M2.7-highspeed\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n\n## Codex Integration\n\nConnect the Codex desktop app to GodeX by adding a custom provider in `~/.codex/config.toml`:\n\n```toml\nmodel = \"gpt-5.5\"\nmodel_provider = \"godex\"\n\n[model_providers.godex]\nname = \"GodeX\"\nbase_url = \"http://127.0.0.1:5678/v1\"\nwire_api = \"responses\"\nrequires_openai_auth = false\nsupports_websockets = false\n```\n\nModel aliases (`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, etc.) are resolved by GodeX using the `models.aliases` map in `godex.yaml` — Codex itself only needs the alias name.\n\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata and final patched request payload summaries\n- Provider request lifecycle events without duplicating full request bodies\n- Sync provider response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes` for trace rows that carry payloads. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "326fc89bd7cd353c1c11b6786594a3809be29115": {"t": 1785748571.086064, "n": 15644, "h": "2f27882cf1815286", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | none  | auto, none, required, function | text, json_object | ✅ | `MiniMax-M2.7` |\n| Zhipu    | boolean | auto, none | text, json_object | ✅ | `glm-5.1` |\n\n## Architecture\n\n```mermaid\nflowchart TB\n  Client[\"Client<br>Codex, SDK, CLI, IDE\"] --> Routes[\"Bun server routes<br>/health<br>/v1/models<br>/v1/responses\"]\n  Routes --> Ctx[\"ResponsesContext<br>request id, response id, resolved model,<br>provider, session, diagnostics\"]\n\n  Ctx --> Resolver[\"ModelResolver<br>alias and provider/model selection\"]\n  Ctx --> Session[\"ResponseSessionStore<br>memory or SQLite<br>previous_response_id chains\"]\n  Ctx --> Registrar[\"Registrar<br>built-in ProviderEdge factories\"]\n  Ctx --> Runtime[\"ResponsesBridgeRuntime\"]\n\n  Runtime --> Sync[\"SyncRequestPipeline\"]\n  Runtime --> Stream[\"StreamPipeline\"]\n  Sync --> Exchange[\"ProviderExchange\"]\n  Stream --> Exchange\n\n  Exchange --> Builder[\"bridge/request<br>buildChatCompletionRequest\"]\n  Builder --> Compat[\"bridge/compatibility<br>parameter and response-format decisions\"]\n  Builder --> Tools[\"bridge/tools<br>tool declarations, tool_choice,<br>identity restoration\"]\n  Builder --> Output[\"bridge/output<br>structured-output contract\"]\n\n  Exchange --> Edge[\"ProviderEdge<br>ProviderSpec + hooks\"]\n  Edge --> ClientHttp[\"ChatProviderClient<br>Fetcher HTTP boundary\"]\n  ClientHttp --> Upstream[\"Chat Completions upstream<br>DeepSeek, Xiaomi, MiniMax, Zhipu, custom\"]\n\n  Upstream --> SyncRecon[\"bridge/response<br>reconstructResponseObject\"]\n  Upstream --> StreamRecon[\"bridge/stream<br>ResponseStreamStateMachine\"]\n  SyncRecon --> ResponseJson[\"ResponseObject JSON\"]\n  StreamRecon --> StreamTransforms[\"stream transforms<br>validate, trace, log, persist, diagnostics\"]\n  StreamTransforms --> Sse[\"Responses SSE\"]\n\n  Ctx --> Trace[\"trace recorder<br>request, usage, event, error rows\"]\n  Ctx --> Logger[\"structured logger\"]\n```\n\n## Component Interaction\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor Client\n  participant Server as /v1/responses route\n  participant Context as ResponsesContext factory\n  participant Resolver as ModelResolver\n  participant Store as ResponseSessionStore\n  participant Registrar\n  participant Runtime as ResponsesBridgeRuntime\n  participant Exchange as ProviderExchange\n  participant Bridge as bridge/request\n  participant Provider as ProviderEdge\n  participant Upstream as Chat Completions API\n\n  Client->>Server: POST /v1/responses\n  Server->>Server: parse and validate JSON envelope\n  Server->>Context: create(app, body)\n  Context->>Resolver: resolve(body.model)\n  Resolver-->>Context: provider + upstream model\n  opt previous_response_id\n    Context->>Store: resolveChain(previous_response_id)\n    Store-->>Context: ordered session snapshot\n  end\n  Context->>Registrar: resolve(provider)\n  Registrar-->>Context: ProviderEdge\n  Server->>Runtime: request(ctx) or stream(ctx)\n  Runtime->>Exchange: build and send provider request\n  Exchange->>Bridge: buildChatCompletionRequest(ctx)\n  Bridge-->>Exchange: chat request + compatibility/tool/output plans\n  Exchange->>Provider: request(body) or stream(body)\n  Provider->>Upstream: POST /chat/completions\n  Upstream-->>Provider: JSON response or SSE chunks\n  alt sync\n    Provider-->>Exchange: provider response\n    Exchange-->>Runtime: provider response + plans\n    Runtime->>Store: save completed response unless store=false\n    Runtime-->>Server: ResponseObject\n    Server-->>Client: JSON\n  else stream\n    Provider-->>Exchange: provider SSE stream\n    Exchange-->>Runtime: stream + plans\n    Runtime->>Runtime: bridge deltas, validate output, trace, log, persist\n    Runtime-->>Server: ResponseStreamEvent stream\n    Server-->>Client: text/event-stream\n  end\n```\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    #\n    # 这些 alias 是 GodeX routing policy，不代表与 OpenAI 原模型能力等价。\n    # 依据优先级：公开 benchmark > 官方模型定位 > Provider 产品说明。\n    # -------------------------------------------------------------------------\n\n    # Codex 默认主力：复杂编码 / computer use / research workflows\n    # 依据：DeepSeek V4-Pro 在 SWE / Terminal / Codeforces / GDPval-AA 上公开成绩强。\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n\n    # Codex 旗舰：coding + reasoning + tool use + agentic workflows\n    # 依据：DeepSeek V4-Pro 有更完整的公开 coding/agentic benchmark 覆盖。\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n\n    # Codex mini：subagents\n    gpt-5.4-mini: \"zhipu/glm-5.1\"\n\n    # Codex 编码专用：复杂软件工程\n    # 依据：DeepSeek V4-Pro 的 SWE Verified / SWE Pro / Terminal Bench 表现。\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n\n    # Codex spark：近实时编码迭代\n    gpt-5.3-codex-spark: \"zhipu/glm-5.1\"\n\n    # 上一代通用 coding / agentic fallback\n    # 严谨起见仍走 DeepSeek；不强行映射到 Zhipu。\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # -------------------------------------------------------------------------\n    # Provider native models\n    # -------------------------------------------------------------------------\n\n    deepseek-v4-pro: \"deepseek/deepseek-v4-pro\"\n    deepseek-v4-flash: \"deepseek/deepseek-v4-flash\"\n\n    mimo-v2.5-pro: \"xiaomi/mimo-v2.5-pro\"\n    mimo-v2.5: \"xiaomi/mimo-v2.5\"\n\n    glm-5.1: \"zhipu/glm-5.1\"\n    glm-5-turbo: \"zhipu/glm-5-turbo\"\n    glm-4.7: \"zhipu/glm-4.7\"\n    glm-4.5-air: \"zhipu/glm-4.5-air\"\n\n    MiniMax-M2.7: \"minimax/MiniMax-M2.7\"\n    MiniMax-M2.7-highspeed: \"minimax/MiniMax-M2.7-highspeed\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n\n## Codex Integration\n\nConnect the Codex desktop app to GodeX by adding a custom provider in `~/.codex/config.toml`:\n\n```toml\nmodel = \"gpt-5.5\"\nmodel_provider = \"godex\"\n\n[model_providers.godex]\nname = \"GodeX\"\nbase_url = \"http://127.0.0.1:5678/v1\"\nwire_api = \"responses\"\nrequires_openai_auth = false\nsupports_websockets = false\n```\n\nModel aliases (`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, etc.) are resolved by GodeX using the `models.aliases` map in `godex.yaml` — Codex itself only needs the alias name.\n\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata and final patched request payload summaries\n- Provider request lifecycle events without duplicating full request bodies\n- Sync provider response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes` for trace rows that carry payloads. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "0f8625a01787149798873fab739909abd4b59446": {"t": 1785748572.6611516, "n": 15698, "h": "bf8b95da945ed8f2", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | none  | auto, none, required, function | text, json_object | ✅ | `MiniMax-M2.7` |\n| Zhipu    | boolean | auto, none | text, json_object | ✅ | `glm-5.1` |\n\n## Architecture\n\n```mermaid\nflowchart TB\n  Client[\"Client<br>Codex, SDK, CLI, IDE\"] --> Routes[\"Bun server routes<br>/health<br>/v1/models<br>/v1/responses\"]\n  Routes --> Ctx[\"ResponsesContext<br>request id, response id, resolved model,<br>provider, session, diagnostics\"]\n\n  Ctx --> Resolver[\"ModelResolver<br>alias and provider/model selection\"]\n  Ctx --> Session[\"ResponseSessionStore<br>memory or SQLite<br>previous_response_id chains\"]\n  Ctx --> Registrar[\"Registrar<br>built-in ProviderEdge factories\"]\n  Ctx --> Runtime[\"ResponsesBridgeRuntime\"]\n\n  Runtime --> Sync[\"SyncRequestPipeline\"]\n  Runtime --> Stream[\"StreamPipeline\"]\n  Sync --> Exchange[\"ProviderExchange\"]\n  Stream --> Exchange\n\n  Exchange --> Builder[\"bridge/request<br>buildChatCompletionRequest\"]\n  Builder --> Compat[\"bridge/compatibility<br>parameter and response-format decisions\"]\n  Builder --> Tools[\"bridge/tools<br>tool declarations, tool_choice,<br>identity restoration\"]\n  Builder --> Output[\"bridge/output<br>structured-output contract\"]\n\n  Exchange --> Edge[\"ProviderEdge<br>ProviderSpec + hooks\"]\n  Edge --> ClientHttp[\"ChatProviderClient<br>Fetcher HTTP boundary\"]\n  ClientHttp --> Upstream[\"Chat Completions upstream<br>DeepSeek, Xiaomi, MiniMax, Zhipu, custom\"]\n\n  Upstream --> SyncRecon[\"bridge/response<br>reconstructResponseObject\"]\n  Upstream --> StreamRecon[\"bridge/stream<br>ResponseStreamStateMachine\"]\n  SyncRecon --> ResponseJson[\"ResponseObject JSON\"]\n  StreamRecon --> StreamTransforms[\"stream transforms<br>validate, trace, log, persist, diagnostics\"]\n  StreamTransforms --> Sse[\"Responses SSE\"]\n\n  Ctx --> Trace[\"trace recorder<br>request, usage, event, error rows\"]\n  Ctx --> Logger[\"structured logger\"]\n```\n\n## Component Interaction\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor Client\n  participant Server as /v1/responses route\n  participant Context as ResponsesContext factory\n  participant Resolver as ModelResolver\n  participant Store as ResponseSessionStore\n  participant Registrar\n  participant Runtime as ResponsesBridgeRuntime\n  participant Exchange as ProviderExchange\n  participant Bridge as bridge/request\n  participant Provider as ProviderEdge\n  participant Upstream as Chat Completions API\n\n  Client->>Server: POST /v1/responses\n  Server->>Server: parse and validate JSON envelope\n  Server->>Context: create(app, body)\n  Context->>Resolver: resolve(body.model)\n  Resolver-->>Context: provider + upstream model\n  opt previous_response_id\n    Context->>Store: resolveChain(previous_response_id)\n    Store-->>Context: ordered session snapshot\n  end\n  Context->>Registrar: resolve(provider)\n  Registrar-->>Context: ProviderEdge\n  Server->>Runtime: request(ctx) or stream(ctx)\n  Runtime->>Exchange: build and send provider request\n  Exchange->>Bridge: buildChatCompletionRequest(ctx)\n  Bridge-->>Exchange: chat request + compatibility/tool/output plans\n  Exchange->>Provider: request(body) or stream(body)\n  Provider->>Upstream: POST /chat/completions\n  Upstream-->>Provider: JSON response or SSE chunks\n  alt sync\n    Provider-->>Exchange: provider response\n    Exchange-->>Runtime: provider response + plans\n    Runtime->>Store: save completed response unless store=false\n    Runtime-->>Server: ResponseObject\n    Server-->>Client: JSON\n  else stream\n    Provider-->>Exchange: provider SSE stream\n    Exchange-->>Runtime: stream + plans\n    Runtime->>Runtime: bridge deltas, validate output, trace, log, persist\n    Runtime-->>Server: ResponseStreamEvent stream\n    Server-->>Client: text/event-stream\n  end\n```\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    #\n    # 这些 alias 是 GodeX routing policy，不代表与 OpenAI 原模型能力等价。\n    # 依据优先级：公开 benchmark > 官方模型定位 > Provider 产品说明。\n    # -------------------------------------------------------------------------\n\n    # Codex 默认主力：复杂编码 / computer use / research workflows\n    # 依据：DeepSeek V4-Pro 在 SWE / Terminal / Codeforces / GDPval-AA 上公开成绩强。\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n\n    # Codex 旗舰：coding + reasoning + tool use + agentic workflows\n    # 依据：DeepSeek V4-Pro 有更完整的公开 coding/agentic benchmark 覆盖。\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n\n    # Codex mini：subagents\n    gpt-5.4-mini: \"zhipu/glm-5.1\"\n\n    # Codex 编码专用：复杂软件工程\n    # 依据：DeepSeek V4-Pro 的 SWE Verified / SWE Pro / Terminal Bench 表现。\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n\n    # Codex spark：近实时编码迭代\n    gpt-5.3-codex-spark: \"zhipu/glm-5.1\"\n\n    # 上一代通用 coding / agentic fallback\n    # 严谨起见仍走 DeepSeek；不强行映射到 Zhipu。\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # -------------------------------------------------------------------------\n    # Provider native models\n    # -------------------------------------------------------------------------\n\n    deepseek-v4-pro: \"deepseek/deepseek-v4-pro\"\n    deepseek-v4-flash: \"deepseek/deepseek-v4-flash\"\n\n    mimo-v2.5-pro: \"xiaomi/mimo-v2.5-pro\"\n    mimo-v2.5: \"xiaomi/mimo-v2.5\"\n\n    glm-5.1: \"zhipu/glm-5.1\"\n    glm-5-turbo: \"zhipu/glm-5-turbo\"\n    glm-4.7: \"zhipu/glm-4.7\"\n    glm-4.5-air: \"zhipu/glm-4.5-air\"\n\n    MiniMax-M2.7: \"minimax/MiniMax-M2.7\"\n    MiniMax-M2.7-highspeed: \"minimax/MiniMax-M2.7-highspeed\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n\n## Codex Integration\n\nConnect the Codex desktop app to GodeX by adding a custom provider in `~/.codex/config.toml`:\n\n```toml\nmodel = \"gpt-5.5\"\nmodel_provider = \"godex\"\n\n[model_providers.godex]\nname = \"GodeX\"\nbase_url = \"http://127.0.0.1:5678/v1\"\nwire_api = \"responses\"\nsupports_websockets = false\n```\n\nModel aliases (`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, etc.) are resolved by GodeX using the `models.aliases` map in `godex.yaml` — Codex itself only needs the alias name. See [Codex 集成配置](docs/references/codex/configuration.md) for the full setup guide.\n\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata and final patched request payload summaries\n- Provider request lifecycle events without duplicating full request bodies\n- Sync provider response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes` for trace rows that carry payloads. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "693b08e5dc5a378238043924e122b99c64e486b8": {"t": 1785748573.7888095, "n": 15140, "h": "c90bc68e3d3a18a6", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | none  | auto, none, required, function | text, json_object | ✅ | `MiniMax-M2.7` |\n| Zhipu    | boolean | auto, none | text, json_object | ✅ | `glm-5.1` |\n\n## Architecture\n\n```mermaid\nflowchart TB\n  Client[\"Client<br>Codex, SDK, CLI, IDE\"] --> Routes[\"Bun server routes<br>/health<br>/v1/models<br>/v1/responses\"]\n  Routes --> Ctx[\"ResponsesContext<br>request id, response id, resolved model,<br>provider, session, diagnostics\"]\n\n  Ctx --> Resolver[\"ModelResolver<br>alias and provider/model selection\"]\n  Ctx --> Session[\"ResponseSessionStore<br>memory or SQLite<br>previous_response_id chains\"]\n  Ctx --> Registrar[\"Registrar<br>built-in ProviderEdge factories\"]\n  Ctx --> Runtime[\"ResponsesBridgeRuntime\"]\n\n  Runtime --> Sync[\"SyncRequestPipeline\"]\n  Runtime --> Stream[\"StreamPipeline\"]\n  Sync --> Exchange[\"ProviderExchange\"]\n  Stream --> Exchange\n\n  Exchange --> Builder[\"bridge/request<br>buildChatCompletionRequest\"]\n  Builder --> Compat[\"bridge/compatibility<br>parameter and response-format decisions\"]\n  Builder --> Tools[\"bridge/tools<br>tool declarations, tool_choice,<br>identity restoration\"]\n  Builder --> Output[\"bridge/output<br>structured-output contract\"]\n\n  Exchange --> Edge[\"ProviderEdge<br>ProviderSpec + hooks\"]\n  Edge --> ClientHttp[\"ChatProviderClient<br>Fetcher HTTP boundary\"]\n  ClientHttp --> Upstream[\"Chat Completions upstream<br>DeepSeek, Xiaomi, MiniMax, Zhipu, custom\"]\n\n  Upstream --> SyncRecon[\"bridge/response<br>reconstructResponseObject\"]\n  Upstream --> StreamRecon[\"bridge/stream<br>ResponseStreamStateMachine\"]\n  SyncRecon --> ResponseJson[\"ResponseObject JSON\"]\n  StreamRecon --> StreamTransforms[\"stream transforms<br>validate, trace, log, persist, diagnostics\"]\n  StreamTransforms --> Sse[\"Responses SSE\"]\n\n  Ctx --> Trace[\"trace recorder<br>request, usage, event, error rows\"]\n  Ctx --> Logger[\"structured logger\"]\n```\n\n## Component Interaction\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor Client\n  participant Server as /v1/responses route\n  participant Context as ResponsesContext factory\n  participant Resolver as ModelResolver\n  participant Store as ResponseSessionStore\n  participant Registrar\n  participant Runtime as ResponsesBridgeRuntime\n  participant Exchange as ProviderExchange\n  participant Bridge as bridge/request\n  participant Provider as ProviderEdge\n  participant Upstream as Chat Completions API\n\n  Client->>Server: POST /v1/responses\n  Server->>Server: parse and validate JSON envelope\n  Server->>Context: create(app, body)\n  Context->>Resolver: resolve(body.model)\n  Resolver-->>Context: provider + upstream model\n  opt previous_response_id\n    Context->>Store: resolveChain(previous_response_id)\n    Store-->>Context: ordered session snapshot\n  end\n  Context->>Registrar: resolve(provider)\n  Registrar-->>Context: ProviderEdge\n  Server->>Runtime: request(ctx) or stream(ctx)\n  Runtime->>Exchange: build and send provider request\n  Exchange->>Bridge: buildChatCompletionRequest(ctx)\n  Bridge-->>Exchange: chat request + compatibility/tool/output plans\n  Exchange->>Provider: request(body) or stream(body)\n  Provider->>Upstream: POST /chat/completions\n  Upstream-->>Provider: JSON response or SSE chunks\n  alt sync\n    Provider-->>Exchange: provider response\n    Exchange-->>Runtime: provider response + plans\n    Runtime->>Store: save completed response unless store=false\n    Runtime-->>Server: ResponseObject\n    Server-->>Client: JSON\n  else stream\n    Provider-->>Exchange: provider SSE stream\n    Exchange-->>Runtime: stream + plans\n    Runtime->>Runtime: bridge deltas, validate output, trace, log, persist\n    Runtime-->>Server: ResponseStreamEvent stream\n    Server-->>Client: text/event-stream\n  end\n```\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    #\n    # 这些 alias 是 GodeX routing policy，不代表与 OpenAI 原模型能力等价。\n    # 依据优先级：公开 benchmark > 官方模型定位 > Provider 产品说明。\n    # -------------------------------------------------------------------------\n\n    # Codex 默认主力：复杂编码 / computer use / research workflows\n    # 依据：DeepSeek V4-Pro 在 SWE / Terminal / Codeforces / GDPval-AA 上公开成绩强。\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n\n    # Codex 旗舰：coding + reasoning + tool use + agentic workflows\n    # 依据：DeepSeek V4-Pro 有更完整的公开 coding/agentic benchmark 覆盖。\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n\n    # Codex mini：subagents\n    gpt-5.4-mini: \"zhipu/glm-5.1\"\n\n    # Codex 编码专用：复杂软件工程\n    # 依据：DeepSeek V4-Pro 的 SWE Verified / SWE Pro / Terminal Bench 表现。\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n\n    # Codex spark：近实时编码迭代\n    gpt-5.3-codex-spark: \"zhipu/glm-5.1\"\n\n    # 上一代通用 coding / agentic fallback\n    # 严谨起见仍走 DeepSeek；不强行映射到 Zhipu。\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # -------------------------------------------------------------------------\n    # Provider native models\n    # -------------------------------------------------------------------------\n\n    deepseek-v4-pro: \"deepseek/deepseek-v4-pro\"\n    deepseek-v4-flash: \"deepseek/deepseek-v4-flash\"\n\n    mimo-v2.5-pro: \"xiaomi/mimo-v2.5-pro\"\n    mimo-v2.5: \"xiaomi/mimo-v2.5\"\n\n    glm-5.1: \"zhipu/glm-5.1\"\n    glm-5-turbo: \"zhipu/glm-5-turbo\"\n    glm-4.7: \"zhipu/glm-4.7\"\n    glm-4.5-air: \"zhipu/glm-4.5-air\"\n\n    MiniMax-M2.7: \"minimax/MiniMax-M2.7\"\n    MiniMax-M2.7-highspeed: \"minimax/MiniMax-M2.7-highspeed\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata and final patched request payload summaries\n- Provider request lifecycle events without duplicating full request bodies\n- Sync provider response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes` for trace rows that carry payloads. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "9b1dbc05bde791a28764f040524ad7b9fb40b1f1": {"t": 1785748574.903143, "n": 15282, "h": "f322d03397bcec1f", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | none  | auto, none, required, function | text, json_object | ✅ | `MiniMax-M2.7` |\n| Zhipu    | boolean | auto, none | text, json_object | ✅ | `glm-5.1` |\n\n## Architecture\n\n```mermaid\nflowchart TB\n  Client[\"Client<br>Codex, SDK, CLI, IDE\"] --> Routes[\"Bun server routes<br>/health<br>/v1/models<br>/v1/responses\"]\n  Routes --> Ctx[\"ResponsesContext<br>request id, response id, resolved model,<br>provider, session, diagnostics\"]\n\n  Ctx --> Resolver[\"ModelResolver<br>alias and provider/model selection\"]\n  Ctx --> Session[\"ResponseSessionStore<br>memory or SQLite<br>previous_response_id chains\"]\n  Ctx --> Registrar[\"Registrar<br>built-in ProviderEdge factories\"]\n  Ctx --> Runtime[\"ResponsesBridgeRuntime\"]\n\n  Runtime --> Sync[\"SyncRequestPipeline\"]\n  Runtime --> Stream[\"StreamPipeline\"]\n  Sync --> Exchange[\"ProviderExchange\"]\n  Stream --> Exchange\n\n  Exchange --> Builder[\"bridge/request<br>buildChatCompletionRequest\"]\n  Builder --> Compat[\"bridge/compatibility<br>parameter and response-format decisions\"]\n  Builder --> Tools[\"bridge/tools<br>tool declarations, tool_choice,<br>identity restoration\"]\n  Builder --> Output[\"bridge/output<br>structured-output contract\"]\n\n  Exchange --> Edge[\"ProviderEdge<br>ProviderSpec + hooks\"]\n  Edge --> ClientHttp[\"ChatProviderClient<br>Fetcher HTTP boundary\"]\n  ClientHttp --> Upstream[\"Chat Completions upstream<br>DeepSeek, Xiaomi, MiniMax, Zhipu, custom\"]\n\n  Upstream --> SyncRecon[\"bridge/response<br>reconstructResponseObject\"]\n  Upstream --> StreamRecon[\"bridge/stream<br>ResponseStreamStateMachine\"]\n  SyncRecon --> ResponseJson[\"ResponseObject JSON\"]\n  StreamRecon --> StreamTransforms[\"stream transforms<br>validate, trace, log, persist, diagnostics\"]\n  StreamTransforms --> Sse[\"Responses SSE\"]\n\n  Ctx --> Trace[\"trace recorder<br>request, usage, event, error rows\"]\n  Ctx --> Logger[\"structured logger\"]\n```\n\n## Component Interaction\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor Client\n  participant Server as /v1/responses route\n  participant Context as ResponsesContext factory\n  participant Resolver as ModelResolver\n  participant Store as ResponseSessionStore\n  participant Registrar\n  participant Runtime as ResponsesBridgeRuntime\n  participant Exchange as ProviderExchange\n  participant Bridge as bridge/request\n  participant Provider as ProviderEdge\n  participant Upstream as Chat Completions API\n\n  Client->>Server: POST /v1/responses\n  Server->>Server: parse and validate JSON envelope\n  Server->>Context: create(app, body)\n  Context->>Resolver: resolve(body.model)\n  Resolver-->>Context: provider + upstream model\n  opt previous_response_id\n    Context->>Store: resolveChain(previous_response_id)\n    Store-->>Context: ordered session snapshot\n  end\n  Context->>Registrar: resolve(provider)\n  Registrar-->>Context: ProviderEdge\n  Server->>Runtime: request(ctx) or stream(ctx)\n  Runtime->>Exchange: build and send provider request\n  Exchange->>Bridge: buildChatCompletionRequest(ctx)\n  Bridge-->>Exchange: chat request + compatibility/tool/output plans\n  Exchange->>Provider: request(body) or stream(body)\n  Provider->>Upstream: POST /chat/completions\n  Upstream-->>Provider: JSON response or SSE chunks\n  alt sync\n    Provider-->>Exchange: provider response\n    Exchange-->>Runtime: provider response + plans\n    Runtime->>Store: save completed response unless store=false\n    Runtime-->>Server: ResponseObject\n    Server-->>Client: JSON\n  else stream\n    Provider-->>Exchange: provider SSE stream\n    Exchange-->>Runtime: stream + plans\n    Runtime->>Runtime: bridge deltas, validate output, trace, log, persist\n    Runtime-->>Server: ResponseStreamEvent stream\n    Server-->>Client: text/event-stream\n  end\n```\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    #\n    # 这些 alias 是 GodeX routing policy，不代表与 OpenAI 原模型能力等价。\n    # 依据优先级：公开 benchmark > 官方模型定位 > Provider 产品说明。\n    # -------------------------------------------------------------------------\n\n    # Codex 默认主力：复杂编码 / computer use / research workflows\n    # 依据：DeepSeek V4-Pro 在 SWE / Terminal / Codeforces / GDPval-AA 上公开成绩强。\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n\n    # Codex 旗舰：coding + reasoning + tool use + agentic workflows\n    # 依据：DeepSeek V4-Pro 有更完整的公开 coding/agentic benchmark 覆盖。\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n\n    # Codex mini：快速、低成本、轻量编码、subagents\n    # 依据：MiniMax M2.7-highspeed 与 M2.7 结果一致但速度更快。\n    gpt-5.4-mini: \"minimax/MiniMax-M2.7-highspeed\"\n\n    # Codex 编码专用：复杂软件工程\n    # 依据：DeepSeek V4-Pro 的 SWE Verified / SWE Pro / Terminal Bench 表现。\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n\n    # Codex spark：近实时编码迭代\n    # 依据：MiniMax highspeed 版本更贴合 spark 的速度定位。\n    gpt-5.3-codex-spark: \"minimax/MiniMax-M2.7-highspeed\"\n\n    # 上一代通用 coding / agentic fallback\n    # 严谨起见仍走 DeepSeek；不强行映射到 Zhipu。\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # -------------------------------------------------------------------------\n    # Provider native models\n    # -------------------------------------------------------------------------\n\n    deepseek-v4-pro: \"deepseek/deepseek-v4-pro\"\n    deepseek-v4-flash: \"deepseek/deepseek-v4-flash\"\n\n    mimo-v2.5-pro: \"xiaomi/mimo-v2.5-pro\"\n    mimo-v2.5: \"xiaomi/mimo-v2.5\"\n\n    glm-5.1: \"zhipu/glm-5.1\"\n    glm-5-turbo: \"zhipu/glm-5-turbo\"\n    glm-4.7: \"zhipu/glm-4.7\"\n    glm-4.5-air: \"zhipu/glm-4.5-air\"\n\n    MiniMax-M2.7: \"minimax/MiniMax-M2.7\"\n    MiniMax-M2.7-highspeed: \"minimax/MiniMax-M2.7-highspeed\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata and final patched request payload summaries\n- Provider request lifecycle events without duplicating full request bodies\n- Sync provider response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes` for trace rows that carry payloads. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "987f4ae12bd1372136723ad78a3ac73587783fbc": {"t": 1785748576.0401459, "n": 15134, "h": "e62612fe6397904d", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | none  | auto, none, required, function | text, json_object | ✅ | `MiniMax-M2.7` |\n| Zhipu    | boolean | auto, none | text, json_object | ✅ | `glm-5.1` |\n\n## Architecture\n\n```mermaid\nflowchart TB\n  Client[\"Client<br>Codex, SDK, CLI, IDE\"] --> Routes[\"Bun server routes<br>/health<br>/v1/models<br>/v1/responses\"]\n  Routes --> Ctx[\"ResponsesContext<br>request id, response id, resolved model,<br>provider, session, diagnostics\"]\n\n  Ctx --> Resolver[\"ModelResolver<br>alias and provider/model selection\"]\n  Ctx --> Session[\"ResponseSessionStore<br>memory or SQLite<br>previous_response_id chains\"]\n  Ctx --> Registrar[\"Registrar<br>built-in ProviderEdge factories\"]\n  Ctx --> Runtime[\"ResponsesBridgeRuntime\"]\n\n  Runtime --> Sync[\"SyncRequestPipeline\"]\n  Runtime --> Stream[\"StreamPipeline\"]\n  Sync --> Exchange[\"ProviderExchange\"]\n  Stream --> Exchange\n\n  Exchange --> Builder[\"bridge/request<br>buildChatCompletionRequest\"]\n  Builder --> Compat[\"bridge/compatibility<br>parameter and response-format decisions\"]\n  Builder --> Tools[\"bridge/tools<br>tool declarations, tool_choice,<br>identity restoration\"]\n  Builder --> Output[\"bridge/output<br>structured-output contract\"]\n\n  Exchange --> Edge[\"ProviderEdge<br>ProviderSpec + hooks\"]\n  Edge --> ClientHttp[\"ChatProviderClient<br>Fetcher HTTP boundary\"]\n  ClientHttp --> Upstream[\"Chat Completions upstream<br>DeepSeek, Xiaomi, MiniMax, Zhipu, custom\"]\n\n  Upstream --> SyncRecon[\"bridge/response<br>reconstructResponseObject\"]\n  Upstream --> StreamRecon[\"bridge/stream<br>ResponseStreamStateMachine\"]\n  SyncRecon --> ResponseJson[\"ResponseObject JSON\"]\n  StreamRecon --> StreamTransforms[\"stream transforms<br>validate, trace, log, persist, diagnostics\"]\n  StreamTransforms --> Sse[\"Responses SSE\"]\n\n  Ctx --> Trace[\"trace recorder<br>request, usage, event, error rows\"]\n  Ctx --> Logger[\"structured logger\"]\n```\n\n## Component Interaction\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor Client\n  participant Server as /v1/responses route\n  participant Context as ResponsesContext factory\n  participant Resolver as ModelResolver\n  participant Store as ResponseSessionStore\n  participant Registrar\n  participant Runtime as ResponsesBridgeRuntime\n  participant Exchange as ProviderExchange\n  participant Bridge as bridge/request\n  participant Provider as ProviderEdge\n  participant Upstream as Chat Completions API\n\n  Client->>Server: POST /v1/responses\n  Server->>Server: parse and validate JSON envelope\n  Server->>Context: create(app, body)\n  Context->>Resolver: resolve(body.model)\n  Resolver-->>Context: provider + upstream model\n  opt previous_response_id\n    Context->>Store: resolveChain(previous_response_id)\n    Store-->>Context: ordered session snapshot\n  end\n  Context->>Registrar: resolve(provider)\n  Registrar-->>Context: ProviderEdge\n  Server->>Runtime: request(ctx) or stream(ctx)\n  Runtime->>Exchange: build and send provider request\n  Exchange->>Bridge: buildChatCompletionRequest(ctx)\n  Bridge-->>Exchange: chat request + compatibility/tool/output plans\n  Exchange->>Provider: request(body) or stream(body)\n  Provider->>Upstream: POST /chat/completions\n  Upstream-->>Provider: JSON response or SSE chunks\n  alt sync\n    Provider-->>Exchange: provider response\n    Exchange-->>Runtime: provider response + plans\n    Runtime->>Store: save completed response unless store=false\n    Runtime-->>Server: ResponseObject\n    Server-->>Client: JSON\n  else stream\n    Provider-->>Exchange: provider SSE stream\n    Exchange-->>Runtime: stream + plans\n    Runtime->>Runtime: bridge deltas, validate output, trace, log, persist\n    Runtime-->>Server: ResponseStreamEvent stream\n    Server-->>Client: text/event-stream\n  end\n```\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    #\n    # 这些 alias 是 GodeX routing policy，不代表与 OpenAI 原模型能力等价。\n    # 依据优先级：公开 benchmark > 官方模型定位 > Provider 产品说明。\n    # -------------------------------------------------------------------------\n\n    # Codex 默认主力：复杂编码 / computer use / research workflows\n    # 依据：DeepSeek V4-Pro 在 SWE / Terminal / Codeforces / GDPval-AA 上公开成绩强。\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n\n    # Codex 旗舰：coding + reasoning + tool use + agentic workflows\n    # 依据：DeepSeek V4-Pro 有更完整的公开 coding/agentic benchmark 覆盖。\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n\n    # Codex mini：快速、低成本、轻量编码、subagents\n    # 依据：MiniMax M2.7-highspeed 与 M2.7 结果一致但速度更快。\n    gpt-5.4-mini: \"minimax/MiniMax-M2.7-highspeed\"\n\n    # Codex 编码专用：复杂软件工程\n    # 依据：DeepSeek V4-Pro 的 SWE Verified / SWE Pro / Terminal Bench 表现。\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n\n    # Codex spark：近实时编码迭代\n    # 依据：MiniMax highspeed 版本更贴合 spark 的速度定位。\n    gpt-5.3-codex-spark: \"minimax/MiniMax-M2.7-highspeed\"\n\n    # 上一代通用 coding / agentic fallback\n    # 严谨起见仍走 DeepSeek；不强行映射到 Zhipu。\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # -------------------------------------------------------------------------\n    # Provider native models\n    # -------------------------------------------------------------------------\n\n    deepseek-v4-pro: \"deepseek/deepseek-v4-pro\"\n    deepseek-v4-flash: \"deepseek/deepseek-v4-flash\"\n\n    mimo-v2.5-pro: \"xiaomi/mimo-v2.5-pro\"\n    mimo-v2.5: \"xiaomi/mimo-v2.5\"\n\n    glm-5.1: \"zhipu/glm-5.1\"\n    glm-5-turbo: \"zhipu/glm-5-turbo\"\n    glm-4.7: \"zhipu/glm-4.7\"\n    glm-4.5-air: \"zhipu/glm-4.5-air\"\n\n    MiniMax-M2.7: \"minimax/MiniMax-M2.7\"\n    MiniMax-M2.7-highspeed: \"minimax/MiniMax-M2.7-highspeed\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata\n- Provider request and response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes`. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "16c3a630764b4abd2230bb1b7bd9195e9454b939": {"t": 1785748577.2231011, "n": 13362, "h": "1c5463d1a6c659ea", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | none  | auto, none, required, function | text, json_object | ✅ | `MiniMax-M2.7` |\n| Zhipu    | boolean | auto, none | text, json_object | ✅ | `glm-5.1` |\n\n## Architecture\n\n```mermaid\nflowchart TB\n  Client[\"Client<br>Codex, SDK, CLI, IDE\"] --> Routes[\"Bun server routes<br>/health<br>/v1/models<br>/v1/responses\"]\n  Routes --> Ctx[\"ResponsesContext<br>request id, response id, resolved model,<br>provider, session, diagnostics\"]\n\n  Ctx --> Resolver[\"ModelResolver<br>alias and provider/model selection\"]\n  Ctx --> Session[\"ResponseSessionStore<br>memory or SQLite<br>previous_response_id chains\"]\n  Ctx --> Registrar[\"Registrar<br>built-in ProviderEdge factories\"]\n  Ctx --> Runtime[\"ResponsesBridgeRuntime\"]\n\n  Runtime --> Sync[\"SyncRequestPipeline\"]\n  Runtime --> Stream[\"StreamPipeline\"]\n  Sync --> Exchange[\"ProviderExchange\"]\n  Stream --> Exchange\n\n  Exchange --> Builder[\"bridge/request<br>buildChatCompletionRequest\"]\n  Builder --> Compat[\"bridge/compatibility<br>parameter and response-format decisions\"]\n  Builder --> Tools[\"bridge/tools<br>tool declarations, tool_choice,<br>identity restoration\"]\n  Builder --> Output[\"bridge/output<br>structured-output contract\"]\n\n  Exchange --> Edge[\"ProviderEdge<br>ProviderSpec + hooks\"]\n  Edge --> ClientHttp[\"ChatProviderClient<br>Fetcher HTTP boundary\"]\n  ClientHttp --> Upstream[\"Chat Completions upstream<br>DeepSeek, Xiaomi, MiniMax, Zhipu, custom\"]\n\n  Upstream --> SyncRecon[\"bridge/response<br>reconstructResponseObject\"]\n  Upstream --> StreamRecon[\"bridge/stream<br>ResponseStreamStateMachine\"]\n  SyncRecon --> ResponseJson[\"ResponseObject JSON\"]\n  StreamRecon --> StreamTransforms[\"stream transforms<br>validate, trace, log, persist, diagnostics\"]\n  StreamTransforms --> Sse[\"Responses SSE\"]\n\n  Ctx --> Trace[\"trace recorder<br>request, usage, event, error rows\"]\n  Ctx --> Logger[\"structured logger\"]\n```\n\n## Component Interaction\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor Client\n  participant Server as /v1/responses route\n  participant Context as ResponsesContext factory\n  participant Resolver as ModelResolver\n  participant Store as ResponseSessionStore\n  participant Registrar\n  participant Runtime as ResponsesBridgeRuntime\n  participant Exchange as ProviderExchange\n  participant Bridge as bridge/request\n  participant Provider as ProviderEdge\n  participant Upstream as Chat Completions API\n\n  Client->>Server: POST /v1/responses\n  Server->>Server: parse and validate JSON envelope\n  Server->>Context: create(app, body)\n  Context->>Resolver: resolve(body.model)\n  Resolver-->>Context: provider + upstream model\n  opt previous_response_id\n    Context->>Store: resolveChain(previous_response_id)\n    Store-->>Context: ordered session snapshot\n  end\n  Context->>Registrar: resolve(provider)\n  Registrar-->>Context: ProviderEdge\n  Server->>Runtime: request(ctx) or stream(ctx)\n  Runtime->>Exchange: build and send provider request\n  Exchange->>Bridge: buildChatCompletionRequest(ctx)\n  Bridge-->>Exchange: chat request + compatibility/tool/output plans\n  Exchange->>Provider: request(body) or stream(body)\n  Provider->>Upstream: POST /chat/completions\n  Upstream-->>Provider: JSON response or SSE chunks\n  alt sync\n    Provider-->>Exchange: provider response\n    Exchange-->>Runtime: provider response + plans\n    Runtime->>Store: save completed response unless store=false\n    Runtime-->>Server: ResponseObject\n    Server-->>Client: JSON\n  else stream\n    Provider-->>Exchange: provider SSE stream\n    Exchange-->>Runtime: stream + plans\n    Runtime->>Runtime: bridge deltas, validate output, trace, log, persist\n    Runtime-->>Server: ResponseStreamEvent stream\n    Server-->>Client: text/event-stream\n  end\n```\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    gpt-5.5: deepseek/deepseek-v4-pro\n    glm: zhipu/glm-5.1\n    \"*\": deepseek/deepseek-v4-flash\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata\n- Provider request and response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes`. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "66be6680ad170f6f28c22c6d45770cc6eae746a3": {"t": 1785748578.5245593, "n": 13372, "h": "7ebf4f36c3ac72a8", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for coding models that expose Chat Completions APIs.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | none  | auto, none, required, function | text, json_object | ✅ | `MiniMax-M2.7` |\n| Zhipu    | boolean | auto, none | text, json_object | ✅ | `glm-5.1` |\n\n## Architecture\n\n```mermaid\nflowchart TB\n  Client[\"Client<br>Codex, SDK, CLI, IDE\"] --> Routes[\"Bun server routes<br>/health<br>/v1/models<br>/v1/responses\"]\n  Routes --> Ctx[\"ResponsesContext<br>request id, response id, resolved model,<br>provider, session, diagnostics\"]\n\n  Ctx --> Resolver[\"ModelResolver<br>alias and provider/model selection\"]\n  Ctx --> Session[\"ResponseSessionStore<br>memory or SQLite<br>previous_response_id chains\"]\n  Ctx --> Registrar[\"Registrar<br>built-in ProviderEdge factories\"]\n  Ctx --> Runtime[\"ResponsesBridgeRuntime\"]\n\n  Runtime --> Sync[\"SyncRequestPipeline\"]\n  Runtime --> Stream[\"StreamPipeline\"]\n  Sync --> Exchange[\"ProviderExchange\"]\n  Stream --> Exchange\n\n  Exchange --> Builder[\"bridge/request<br>buildChatCompletionRequest\"]\n  Builder --> Compat[\"bridge/compatibility<br>parameter and response-format decisions\"]\n  Builder --> Tools[\"bridge/tools<br>tool declarations, tool_choice,<br>identity restoration\"]\n  Builder --> Output[\"bridge/output<br>structured-output contract\"]\n\n  Exchange --> Edge[\"ProviderEdge<br>ProviderSpec + hooks\"]\n  Edge --> ClientHttp[\"ChatProviderClient<br>Fetcher HTTP boundary\"]\n  ClientHttp --> Upstream[\"Chat Completions upstream<br>DeepSeek, Xiaomi, MiniMax, Zhipu, custom\"]\n\n  Upstream --> SyncRecon[\"bridge/response<br>reconstructResponseObject\"]\n  Upstream --> StreamRecon[\"bridge/stream<br>ResponseStreamStateMachine\"]\n  SyncRecon --> ResponseJson[\"ResponseObject JSON\"]\n  StreamRecon --> StreamTransforms[\"stream transforms<br>validate, trace, log, persist, diagnostics\"]\n  StreamTransforms --> Sse[\"Responses SSE\"]\n\n  Ctx --> Trace[\"trace recorder<br>request, usage, event, error rows\"]\n  Ctx --> Logger[\"structured logger\"]\n```\n\n## Component Interaction\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor Client\n  participant Server as /v1/responses route\n  participant Context as ResponsesContext factory\n  participant Resolver as ModelResolver\n  participant Store as ResponseSessionStore\n  participant Registrar\n  participant Runtime as ResponsesBridgeRuntime\n  participant Exchange as ProviderExchange\n  participant Bridge as bridge/request\n  participant Provider as ProviderEdge\n  participant Upstream as Chat Completions API\n\n  Client->>Server: POST /v1/responses\n  Server->>Server: parse and validate JSON envelope\n  Server->>Context: create(app, body)\n  Context->>Resolver: resolve(body.model)\n  Resolver-->>Context: provider + upstream model\n  opt previous_response_id\n    Context->>Store: resolveChain(previous_response_id)\n    Store-->>Context: ordered session snapshot\n  end\n  Context->>Registrar: resolve(provider)\n  Registrar-->>Context: ProviderEdge\n  Server->>Runtime: request(ctx) or stream(ctx)\n  Runtime->>Exchange: build and send provider request\n  Exchange->>Bridge: buildChatCompletionRequest(ctx)\n  Bridge-->>Exchange: chat request + compatibility/tool/output plans\n  Exchange->>Provider: request(body) or stream(body)\n  Provider->>Upstream: POST /chat/completions\n  Upstream-->>Provider: JSON response or SSE chunks\n  alt sync\n    Provider-->>Exchange: provider response\n    Exchange-->>Runtime: provider response + plans\n    Runtime->>Store: save completed response unless store=false\n    Runtime-->>Server: ResponseObject\n    Server-->>Client: JSON\n  else stream\n    Provider-->>Exchange: provider SSE stream\n    Exchange-->>Runtime: stream + plans\n    Runtime->>Runtime: bridge deltas, validate output, trace, log, persist\n    Runtime-->>Server: ResponseStreamEvent stream\n    Server-->>Client: text/event-stream\n  end\n```\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    gpt-5.5: deepseek/deepseek-v4-pro\n    glm: zhipu/glm-5.1\n    \"*\": deepseek/deepseek-v4-flash\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata\n- Provider request and response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes`. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "23c3f87dc2600740b2011b31249d6799d3fecd1a": {"t": 1785748580.6654832, "n": 13290, "h": "91744e0a7e522393", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for coding models that expose Chat Completions APIs.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | none  | auto, none, required, function | text, json_object | ✅ | `MiniMax-M2.7` |\n| Zhipu    | boolean | auto, none | text, json_object | ✅ | `glm-5.1` |\n\n## Architecture\n\n```mermaid\nflowchart TB\n  Client[\"Client<br>Codex, SDK, CLI, IDE\"] --> Routes[\"Bun server routes<br>/health<br>/v1/models<br>/v1/responses\"]\n  Routes --> Ctx[\"ResponsesContext<br>request id, response id, resolved model,<br>provider, session, diagnostics\"]\n\n  Ctx --> Resolver[\"ModelResolver<br>alias and provider/model selection\"]\n  Ctx --> Session[\"ResponseSessionStore<br>memory or SQLite<br>previous_response_id chains\"]\n  Ctx --> Registrar[\"Registrar<br>built-in ProviderEdge factories\"]\n  Ctx --> Runtime[\"ResponsesBridgeRuntime\"]\n\n  Runtime --> Sync[\"SyncRequestPipeline\"]\n  Runtime --> Stream[\"StreamPipeline\"]\n  Sync --> Exchange[\"ProviderExchange\"]\n  Stream --> Exchange\n\n  Exchange --> Builder[\"bridge/request<br>buildChatCompletionRequest\"]\n  Builder --> Compat[\"bridge/compatibility<br>parameter and response-format decisions\"]\n  Builder --> Tools[\"bridge/tools<br>tool declarations, tool_choice,<br>identity restoration\"]\n  Builder --> Output[\"bridge/output<br>structured-output contract\"]\n\n  Exchange --> Edge[\"ProviderEdge<br>ProviderSpec + hooks\"]\n  Edge --> ClientHttp[\"ChatProviderClient<br>Fetcher HTTP boundary\"]\n  ClientHttp --> Upstream[\"Chat Completions upstream<br>DeepSeek, Xiaomi, MiniMax, Zhipu, custom\"]\n\n  Upstream --> SyncRecon[\"bridge/response<br>reconstructResponseObject\"]\n  Upstream --> StreamRecon[\"bridge/stream<br>ResponseStreamStateMachine\"]\n  SyncRecon --> ResponseJson[\"ResponseObject JSON\"]\n  StreamRecon --> StreamTransforms[\"stream transforms<br>validate, trace, log, persist, diagnostics\"]\n  StreamTransforms --> Sse[\"Responses SSE\"]\n\n  Ctx --> Trace[\"trace recorder<br>request, usage, event, error rows\"]\n  Ctx --> Logger[\"structured logger\"]\n```\n\n## Component Interaction\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor Client\n  participant Server as /v1/responses route\n  participant Context as ResponsesContext factory\n  participant Resolver as ModelResolver\n  participant Store as ResponseSessionStore\n  participant Registrar\n  participant Runtime as ResponsesBridgeRuntime\n  participant Exchange as ProviderExchange\n  participant Bridge as bridge/request\n  participant Provider as ProviderEdge\n  participant Upstream as Chat Completions API\n\n  Client->>Server: POST /v1/responses\n  Server->>Server: parse and validate JSON envelope\n  Server->>Context: create(app, body)\n  Context->>Resolver: resolve(body.model)\n  Resolver-->>Context: provider + upstream model\n  opt previous_response_id\n    Context->>Store: resolveChain(previous_response_id)\n    Store-->>Context: ordered session snapshot\n  end\n  Context->>Registrar: resolve(provider)\n  Registrar-->>Context: ProviderEdge\n  Server->>Runtime: request(ctx) or stream(ctx)\n  Runtime->>Exchange: build and send provider request\n  Exchange->>Bridge: buildChatCompletionRequest(ctx)\n  Bridge-->>Exchange: chat request + compatibility/tool/output plans\n  Exchange->>Provider: request(body) or stream(body)\n  Provider->>Upstream: POST /chat/completions\n  Upstream-->>Provider: JSON response or SSE chunks\n  alt sync\n    Provider-->>Exchange: provider response\n    Exchange-->>Runtime: provider response + plans\n    Runtime->>Store: save completed response unless store=false\n    Runtime-->>Server: ResponseObject\n    Server-->>Client: JSON\n  else stream\n    Provider-->>Exchange: provider SSE stream\n    Exchange-->>Runtime: stream + plans\n    Runtime->>Runtime: bridge deltas, validate output, trace, log, persist\n    Runtime-->>Server: ResponseStreamEvent stream\n    Server-->>Client: text/event-stream\n  end\n```\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config interactively:\n\n```bash\ngodex init\n```\n\nOr create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    gpt-5.5: deepseek/deepseek-v4-pro\n    glm: zhipu/glm-5.1\n    \"*\": deepseek/deepseek-v4-flash\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nsession:\n  backend: sqlite\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nDuring development you can run from source:\n\n```bash\nbun run dev\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata\n- Provider request and response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes`. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "101ceb263ea68ea8a1ea28820902fadc5442f283": {"t": 1785748581.7574787, "n": 12959, "h": "d76fa2965cde857b", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for coding models that expose Chat Completions APIs.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, MiniMax, and Zhipu through one local server.\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| MiniMax  | none  | auto, none, required, function | text, json_object | ✅ | `MiniMax-M2.7` |\n| Zhipu    | boolean | auto, none | text, json_object | ✅ | `glm-5.1` |\n\n## Architecture\n\n```mermaid\nflowchart TB\n  Client[\"Client<br>Codex, SDK, CLI, IDE\"] --> Routes[\"Bun server routes<br>/health<br>/v1/models<br>/v1/responses\"]\n  Routes --> Ctx[\"ResponsesContext<br>request id, response id, resolved model,<br>provider, session, diagnostics\"]\n\n  Ctx --> Resolver[\"ModelResolver<br>alias and provider/model selection\"]\n  Ctx --> Session[\"ResponseSessionStore<br>memory or SQLite<br>previous_response_id chains\"]\n  Ctx --> Registrar[\"Registrar<br>built-in ProviderEdge factories\"]\n  Ctx --> Runtime[\"ResponsesBridgeRuntime\"]\n\n  Runtime --> Sync[\"SyncRequestPipeline\"]\n  Runtime --> Stream[\"StreamPipeline\"]\n  Sync --> Exchange[\"ProviderExchange\"]\n  Stream --> Exchange\n\n  Exchange --> Builder[\"bridge/request<br>buildChatCompletionRequest\"]\n  Builder --> Compat[\"bridge/compatibility<br>parameter and response-format decisions\"]\n  Builder --> Tools[\"bridge/tools<br>tool declarations, tool_choice,<br>identity restoration\"]\n  Builder --> Output[\"bridge/output<br>structured-output contract\"]\n\n  Exchange --> Edge[\"ProviderEdge<br>ProviderSpec + hooks\"]\n  Edge --> ClientHttp[\"ChatProviderClient<br>Fetcher HTTP boundary\"]\n  ClientHttp --> Upstream[\"Chat Completions upstream<br>DeepSeek, MiniMax, Zhipu, custom\"]\n\n  Upstream --> SyncRecon[\"bridge/response<br>reconstructResponseObject\"]\n  Upstream --> StreamRecon[\"bridge/stream<br>ResponseStreamStateMachine\"]\n  SyncRecon --> ResponseJson[\"ResponseObject JSON\"]\n  StreamRecon --> StreamTransforms[\"stream transforms<br>validate, trace, log, persist, diagnostics\"]\n  StreamTransforms --> Sse[\"Responses SSE\"]\n\n  Ctx --> Trace[\"trace recorder<br>request, usage, event, error rows\"]\n  Ctx --> Logger[\"structured logger\"]\n```\n\n## Component Interaction\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor Client\n  participant Server as /v1/responses route\n  participant Context as ResponsesContext factory\n  participant Resolver as ModelResolver\n  participant Store as ResponseSessionStore\n  participant Registrar\n  participant Runtime as ResponsesBridgeRuntime\n  participant Exchange as ProviderExchange\n  participant Bridge as bridge/request\n  participant Provider as ProviderEdge\n  participant Upstream as Chat Completions API\n\n  Client->>Server: POST /v1/responses\n  Server->>Server: parse and validate JSON envelope\n  Server->>Context: create(app, body)\n  Context->>Resolver: resolve(body.model)\n  Resolver-->>Context: provider + upstream model\n  opt previous_response_id\n    Context->>Store: resolveChain(previous_response_id)\n    Store-->>Context: ordered session snapshot\n  end\n  Context->>Registrar: resolve(provider)\n  Registrar-->>Context: ProviderEdge\n  Server->>Runtime: request(ctx) or stream(ctx)\n  Runtime->>Exchange: build and send provider request\n  Exchange->>Bridge: buildChatCompletionRequest(ctx)\n  Bridge-->>Exchange: chat request + compatibility/tool/output plans\n  Exchange->>Provider: request(body) or stream(body)\n  Provider->>Upstream: POST /chat/completions\n  Upstream-->>Provider: JSON response or SSE chunks\n  alt sync\n    Provider-->>Exchange: provider response\n    Exchange-->>Runtime: provider response + plans\n    Runtime->>Store: save completed response unless store=false\n    Runtime-->>Server: ResponseObject\n    Server-->>Client: JSON\n  else stream\n    Provider-->>Exchange: provider SSE stream\n    Exchange-->>Runtime: stream + plans\n    Runtime->>Runtime: bridge deltas, validate output, trace, log, persist\n    Runtime-->>Server: ResponseStreamEvent stream\n    Server-->>Client: text/event-stream\n  end\n```\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config interactively:\n\n```bash\ngodex init\n```\n\nOr create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    gpt-5.5: deepseek/deepseek-v4-pro\n    glm: zhipu/glm-5.1\n    \"*\": deepseek/deepseek-v4-flash\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n\nsession:\n  backend: sqlite\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nDuring development you can run from source:\n\n```bash\nbun run dev\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata\n- Provider request and response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes`. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "a8af5f8b9bdb48050a26dbb64721c2d81f8431ba": {"t": 1785748582.8205948, "n": 12491, "h": "872159e1493a16e9", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for coding models that expose Chat Completions APIs.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, MiniMax, and Zhipu through one local server.\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Architecture\n\n```mermaid\nflowchart TB\n  Client[\"Client<br>Codex, SDK, CLI, IDE\"] --> Routes[\"Bun server routes<br>/health<br>/v1/models<br>/v1/responses\"]\n  Routes --> Ctx[\"ResponsesContext<br>request id, response id, resolved model,<br>provider, session, diagnostics\"]\n\n  Ctx --> Resolver[\"ModelResolver<br>alias and provider/model selection\"]\n  Ctx --> Session[\"ResponseSessionStore<br>memory or SQLite<br>previous_response_id chains\"]\n  Ctx --> Registrar[\"Registrar<br>built-in ProviderEdge factories\"]\n  Ctx --> Runtime[\"ResponsesBridgeRuntime\"]\n\n  Runtime --> Sync[\"SyncRequestPipeline\"]\n  Runtime --> Stream[\"StreamPipeline\"]\n  Sync --> Exchange[\"ProviderExchange\"]\n  Stream --> Exchange\n\n  Exchange --> Builder[\"bridge/request<br>buildChatCompletionRequest\"]\n  Builder --> Compat[\"bridge/compatibility<br>parameter and response-format decisions\"]\n  Builder --> Tools[\"bridge/tools<br>tool declarations, tool_choice,<br>identity restoration\"]\n  Builder --> Output[\"bridge/output<br>structured-output contract\"]\n\n  Exchange --> Edge[\"ProviderEdge<br>ProviderSpec + hooks\"]\n  Edge --> ClientHttp[\"ChatProviderClient<br>Fetcher HTTP boundary\"]\n  ClientHttp --> Upstream[\"Chat Completions upstream<br>DeepSeek, MiniMax, Zhipu, custom\"]\n\n  Upstream --> SyncRecon[\"bridge/response<br>reconstructResponseObject\"]\n  Upstream --> StreamRecon[\"bridge/stream<br>ResponseStreamStateMachine\"]\n  SyncRecon --> ResponseJson[\"ResponseObject JSON\"]\n  StreamRecon --> StreamTransforms[\"stream transforms<br>validate, trace, log, persist, diagnostics\"]\n  StreamTransforms --> Sse[\"Responses SSE\"]\n\n  Ctx --> Trace[\"trace recorder<br>request, usage, event, error rows\"]\n  Ctx --> Logger[\"structured logger\"]\n```\n\n## Component Interaction\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor Client\n  participant Server as /v1/responses route\n  participant Context as ResponsesContext factory\n  participant Resolver as ModelResolver\n  participant Store as ResponseSessionStore\n  participant Registrar\n  participant Runtime as ResponsesBridgeRuntime\n  participant Exchange as ProviderExchange\n  participant Bridge as bridge/request\n  participant Provider as ProviderEdge\n  participant Upstream as Chat Completions API\n\n  Client->>Server: POST /v1/responses\n  Server->>Server: parse and validate JSON envelope\n  Server->>Context: create(app, body)\n  Context->>Resolver: resolve(body.model)\n  Resolver-->>Context: provider + upstream model\n  opt previous_response_id\n    Context->>Store: resolveChain(previous_response_id)\n    Store-->>Context: ordered session snapshot\n  end\n  Context->>Registrar: resolve(provider)\n  Registrar-->>Context: ProviderEdge\n  Server->>Runtime: request(ctx) or stream(ctx)\n  Runtime->>Exchange: build and send provider request\n  Exchange->>Bridge: buildChatCompletionRequest(ctx)\n  Bridge-->>Exchange: chat request + compatibility/tool/output plans\n  Exchange->>Provider: request(body) or stream(body)\n  Provider->>Upstream: POST /chat/completions\n  Upstream-->>Provider: JSON response or SSE chunks\n  alt sync\n    Provider-->>Exchange: provider response\n    Exchange-->>Runtime: provider response + plans\n    Runtime->>Store: save completed response unless store=false\n    Runtime-->>Server: ResponseObject\n    Server-->>Client: JSON\n  else stream\n    Provider-->>Exchange: provider SSE stream\n    Exchange-->>Runtime: stream + plans\n    Runtime->>Runtime: bridge deltas, validate output, trace, log, persist\n    Runtime-->>Server: ResponseStreamEvent stream\n    Server-->>Client: text/event-stream\n  end\n```\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config interactively:\n\n```bash\ngodex init\n```\n\nOr create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    gpt-5.5: deepseek/deepseek-v4-pro\n    glm: zhipu/glm-5.1\n    \"*\": deepseek/deepseek-v4-flash\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n\nsession:\n  backend: sqlite\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nDuring development you can run from source:\n\n```bash\nbun run dev\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata\n- Provider request and response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes`. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "ee20581d84f68699f28688ba8a6cd23a47e1d258": {"t": 1785748584.0912974, "n": 12138, "h": "934dfcb3df0fd697", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for coding models that expose Chat Completions APIs.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek and Zhipu through one local server.\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Architecture\n\n```mermaid\nflowchart TB\n  Client[\"Client<br>Codex, SDK, CLI, IDE\"] --> Routes[\"Bun server routes<br>/health<br>/v1/models<br>/v1/responses\"]\n  Routes --> Ctx[\"ResponsesContext<br>request id, response id, resolved model,<br>provider, session, diagnostics\"]\n\n  Ctx --> Resolver[\"ModelResolver<br>alias and provider/model selection\"]\n  Ctx --> Session[\"ResponseSessionStore<br>memory or SQLite<br>previous_response_id chains\"]\n  Ctx --> Registrar[\"Registrar<br>built-in ProviderEdge factories\"]\n  Ctx --> Runtime[\"ResponsesBridgeRuntime\"]\n\n  Runtime --> Sync[\"SyncRequestPipeline\"]\n  Runtime --> Stream[\"StreamPipeline\"]\n  Sync --> Exchange[\"ProviderExchange\"]\n  Stream --> Exchange\n\n  Exchange --> Builder[\"bridge/request<br>buildChatCompletionRequest\"]\n  Builder --> Compat[\"bridge/compatibility<br>parameter and response-format decisions\"]\n  Builder --> Tools[\"bridge/tools<br>tool declarations, tool_choice,<br>identity restoration\"]\n  Builder --> Output[\"bridge/output<br>structured-output contract\"]\n\n  Exchange --> Edge[\"ProviderEdge<br>ProviderSpec + hooks\"]\n  Edge --> ClientHttp[\"ChatProviderClient<br>Fetcher HTTP boundary\"]\n  ClientHttp --> Upstream[\"Chat Completions upstream<br>DeepSeek, Zhipu, custom\"]\n\n  Upstream --> SyncRecon[\"bridge/response<br>reconstructResponseObject\"]\n  Upstream --> StreamRecon[\"bridge/stream<br>ResponseStreamStateMachine\"]\n  SyncRecon --> ResponseJson[\"ResponseObject JSON\"]\n  StreamRecon --> StreamTransforms[\"stream transforms<br>validate, trace, log, persist, diagnostics\"]\n  StreamTransforms --> Sse[\"Responses SSE\"]\n\n  Ctx --> Trace[\"trace recorder<br>request, usage, event, error rows\"]\n  Ctx --> Logger[\"structured logger\"]\n```\n\n## Component Interaction\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor Client\n  participant Server as /v1/responses route\n  participant Context as ResponsesContext factory\n  participant Resolver as ModelResolver\n  participant Store as ResponseSessionStore\n  participant Registrar\n  participant Runtime as ResponsesBridgeRuntime\n  participant Exchange as ProviderExchange\n  participant Bridge as bridge/request\n  participant Provider as ProviderEdge\n  participant Upstream as Chat Completions API\n\n  Client->>Server: POST /v1/responses\n  Server->>Server: parse and validate JSON envelope\n  Server->>Context: create(app, body)\n  Context->>Resolver: resolve(body.model)\n  Resolver-->>Context: provider + upstream model\n  opt previous_response_id\n    Context->>Store: resolveChain(previous_response_id)\n    Store-->>Context: ordered session snapshot\n  end\n  Context->>Registrar: resolve(provider)\n  Registrar-->>Context: ProviderEdge\n  Server->>Runtime: request(ctx) or stream(ctx)\n  Runtime->>Exchange: build and send provider request\n  Exchange->>Bridge: buildChatCompletionRequest(ctx)\n  Bridge-->>Exchange: chat request + compatibility/tool/output plans\n  Exchange->>Provider: request(body) or stream(body)\n  Provider->>Upstream: POST /chat/completions\n  Upstream-->>Provider: JSON response or SSE chunks\n  alt sync\n    Provider-->>Exchange: provider response\n    Exchange-->>Runtime: provider response + plans\n    Runtime->>Store: save completed response unless store=false\n    Runtime-->>Server: ResponseObject\n    Server-->>Client: JSON\n  else stream\n    Provider-->>Exchange: provider SSE stream\n    Exchange-->>Runtime: stream + plans\n    Runtime->>Runtime: bridge deltas, validate output, trace, log, persist\n    Runtime-->>Server: ResponseStreamEvent stream\n    Server-->>Client: text/event-stream\n  end\n```\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config interactively:\n\n```bash\ngodex init\n```\n\nOr create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    gpt-5.5: deepseek/deepseek-v4-pro\n    glm: zhipu/glm-5.1\n    \"*\": deepseek/deepseek-v4-flash\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n\nsession:\n  backend: sqlite\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nDuring development you can run from source:\n\n```bash\nbun run dev\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata\n- Provider request and response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes`. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "f2212a8595ffadf31d446bb3acb5e4a95bfa90e1": {"t": 1785748585.1749413, "n": 11550, "h": "c8ccb6cbc589a9a1", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for coding models that expose Chat Completions APIs.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek and Zhipu through one local server.\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Architecture\n\n```mermaid\nflowchart TB\n  Client[\"Client<br>Codex, SDK, CLI, IDE\"] --> Routes[\"Bun server routes<br>/health<br>/v1/models<br>/v1/responses\"]\n  Routes --> Ctx[\"ResponsesContext<br>request id, response id, resolved model,<br>provider, session, diagnostics\"]\n\n  Ctx --> Resolver[\"ModelResolver<br>alias and provider/model selection\"]\n  Ctx --> Session[\"ResponseSessionStore<br>memory or SQLite<br>previous_response_id chains\"]\n  Ctx --> Registrar[\"Registrar<br>built-in ProviderEdge factories\"]\n  Ctx --> Runtime[\"ResponsesBridgeRuntime\"]\n\n  Runtime --> Sync[\"SyncRequestPipeline\"]\n  Runtime --> Stream[\"StreamPipeline\"]\n  Sync --> Exchange[\"ProviderExchange\"]\n  Stream --> Exchange\n\n  Exchange --> Builder[\"bridge/request<br>buildChatCompletionRequest\"]\n  Builder --> Compat[\"bridge/compatibility<br>parameter and response-format decisions\"]\n  Builder --> Tools[\"bridge/tools<br>tool declarations, tool_choice,<br>identity restoration\"]\n  Builder --> Output[\"bridge/output<br>structured-output contract\"]\n\n  Exchange --> Edge[\"ProviderEdge<br>ProviderSpec + hooks\"]\n  Edge --> ClientHttp[\"ChatProviderClient<br>Fetcher HTTP boundary\"]\n  ClientHttp --> Upstream[\"Chat Completions upstream<br>DeepSeek, Zhipu, custom\"]\n\n  Upstream --> SyncRecon[\"bridge/response<br>reconstructResponseObject\"]\n  Upstream --> StreamRecon[\"bridge/stream<br>ResponseStreamStateMachine\"]\n  SyncRecon --> ResponseJson[\"ResponseObject JSON\"]\n  StreamRecon --> StreamTransforms[\"stream transforms<br>validate, trace, log, persist, diagnostics\"]\n  StreamTransforms --> Sse[\"Responses SSE\"]\n\n  Ctx --> Trace[\"trace recorder<br>request, usage, event, error rows\"]\n  Ctx --> Logger[\"structured logger\"]\n```\n\n## Component Interaction\n\n```mermaid\nsequenceDiagram\n  autonumber\n  actor Client\n  participant Server as /v1/responses route\n  participant Context as ResponsesContext factory\n  participant Resolver as ModelResolver\n  participant Store as ResponseSessionStore\n  participant Registrar\n  participant Runtime as ResponsesBridgeRuntime\n  participant Exchange as ProviderExchange\n  participant Bridge as bridge/request\n  participant Provider as ProviderEdge\n  participant Upstream as Chat Completions API\n\n  Client->>Server: POST /v1/responses\n  Server->>Server: parse and validate JSON envelope\n  Server->>Context: create(app, body)\n  Context->>Resolver: resolve(body.model)\n  Resolver-->>Context: provider + upstream model\n  opt previous_response_id\n    Context->>Store: resolveChain(previous_response_id)\n    Store-->>Context: ordered session snapshot\n  end\n  Context->>Registrar: resolve(provider)\n  Registrar-->>Context: ProviderEdge\n  Server->>Runtime: request(ctx) or stream(ctx)\n  Runtime->>Exchange: build and send provider request\n  Exchange->>Bridge: buildChatCompletionRequest(ctx)\n  Bridge-->>Exchange: chat request + compatibility/tool/output plans\n  Exchange->>Provider: request(body) or stream(body)\n  Provider->>Upstream: POST /chat/completions\n  Upstream-->>Provider: JSON response or SSE chunks\n  alt sync\n    Provider-->>Exchange: provider response\n    Exchange-->>Runtime: provider response + plans\n    Runtime->>Store: save completed response unless store=false\n    Runtime-->>Server: ResponseObject\n    Server-->>Client: JSON\n  else stream\n    Provider-->>Exchange: provider SSE stream\n    Exchange-->>Runtime: stream + plans\n    Runtime->>Runtime: bridge deltas, validate output, trace, log, persist\n    Runtime-->>Server: ResponseStreamEvent stream\n    Server-->>Client: text/event-stream\n  end\n```\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n## Quick Start\n\nCreate a config interactively:\n\n```bash\ngodex init\n```\n\nOr create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    gpt-5.5: deepseek/deepseek-v4-pro\n    glm: zhipu/glm-5.1\n    \"*\": deepseek/deepseek-v4-flash\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n\nsession:\n  backend: sqlite\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nDuring development you can run from source:\n\n```bash\nbun run dev\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata\n- Provider request and response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes`. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}, "bbd9ffb5bef87e569356ff8938f16b79f1f4603d": {"t": 1785748586.4339979, "n": 14483, "h": "dacc02b25ff80a32", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway — translates `/v1/responses` into upstream Chat Completions API calls, connecting Codex, CLI, IDE, and automation tools with any model provider.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n[Getting Started](https://godex.ahoo.me/01-getting-started/overview) · [Architecture](https://godex.ahoo.me/02-architecture/overview) · [Configuration](https://godex.ahoo.me/07-configuration/config-schema) · [Documentation](https://godex.ahoo.me)\n\n</div>\n\n## Features\n\n| | Feature | Description |\n|---|---------|-------------|\n| 🔄 | **Protocol Translation** | Bridges OpenAI Responses API and provider-specific Chat Completions APIs |\n| 🔌 | **Provider-agnostic** | Plugin-based adapter system — add providers by implementing a small set of interfaces |\n| ⚡ | **Streaming-first** | `TransformStream` pipeline with trace, validation, logging, session persistence, and SSE delivery |\n| 💾 | **Session History** | Built-in `previous_response_id` chain resolution (SQLite / in-memory) |\n| 🛡️ | **Structured Errors** | Domain-specific error hierarchy with structured codes and diagnostic context |\n| 🔧 | **Built-in Tools** | `local_shell`, `shell`, `apply_patch` — Codex-compatible function tools |\n| 📦 | **Standalone Binary** | Zero runtime dependencies, 6 platform builds via GitHub Actions |\n\n## Quick Start\n\n```bash\n# Install — no Bun required at runtime\nnpm install -g @ahoo-wang/godex\n\n# Create config interactively\ngodex init\n\n# Start the gateway\ngodex serve\n```\n\nPoint Codex CLI at your GodeX instance:\n\n```bash\nexport OPENAI_BASE_URL=http://localhost:5678/v1\nexport OPENAI_API_KEY=any-value          # not validated by GodeX, must be set\ncodex\n```\n\nOr use the OpenAI SDK:\n\n```ts\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n  baseURL: \"http://localhost:5678/v1\",\n  apiKey: \"any-value\",\n});\n\nconst response = await client.responses.create({\n  model: \"gpt-4o\",          // resolved via models.aliases → zhipu/glm-4.7\n  input: \"Hello!\",\n});\n```\n\n## How It Works\n\n```\nCodex / CLI / IDE\n      │\n      ▼  POST /v1/responses\n┌─────────────────────────────────────────┐\n│              GodeX Gateway              │\n│                                         │\n│  Bun.serve → handleResponses()          │\n│       → ResponsesContext.create()       │\n│           → ModelResolver.resolve()     │\n│           → Registrar.resolve()         │\n│       → DefaultAdapter.stream/request() │\n│           → ProviderMapper.map()        │\n│           → ChatClient.streamChat()     │\n│           → TransformStream pipeline    │\n│       → Response (JSON or SSE)          │\n└──────────────┬──────────────────────────┘\n               │  Provider Adapter\n               ▼\n┌─────────────────────────────────────────┐\n│       Chat Completions-compatible API   │\n│       (Zhipu, DeepSeek, or custom)      │\n└─────────────────────────────────────────┘\n```\n\nResponses-native upstreams already speak the target API; point clients at them directly instead of configuring them as GodeX providers.\n\n## Architecture\n\n```mermaid\nC4Context\n  title GodeX — System Context\n\n  Person(user, \"Developer / Codex CLI\", \"Sends Responses API requests<br/>via the OpenAI-compatible endpoint\")\n  System(godex_svr, \"GodeX Server\", \"Translates Responses API → Chat Completions API<br/>Bun.serve on configurable port\")\n  SystemDb(sessions, \"Session Store\", \"Stores response history for<br/>previous_response_id chain resolution<br/>SQLite (persistent) or In-Memory\")\n  System_Ext(zhipu, \"Zhipu (智谱)\", \"Chat Completions API provider\")\n  System_Ext(deepseek, \"DeepSeek\", \"Chat Completions API provider\")\n  System_Ext(other, \"Custom Provider\", \"Any Chat Completions<br/>compatible backend\")\n\n  Rel(user, godex_svr, \"POST /v1/responses, GET /v1/models, GET /health\", \"HTTP/SSE\")\n  Rel(godex_svr, sessions, \"save / resolve chains\")\n  Rel(godex_svr, zhipu, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, deepseek, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, other, \"POST /chat/completions\", \"HTTPS\")\n```\n\n## Component Model\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class ApplicationContext {\n    +config: GodeXConfig\n    +logger: Logger\n    +resolver: ModelResolver\n    +registrar: Registrar\n    +adapter: Adapter\n    +sessionStore: ResponseSessionStore\n  }\n\n  class ResponsesContext {\n    +app: ApplicationContext\n    +request: ResponseCreateRequest\n    +session: ResponseSessionSnapshot\n    +resolved: ResolvedModel\n    +provider: Provider\n    +responseId: string\n    +requestId: string\n    +attributes: Map\n    +create(app, body)$ Promise~ResponsesContext~\n  }\n\n  class ModelResolver {\n    -defaultProvider: string\n    -providerConfigs: Record\n    +resolve(model) ResolvedModel\n  }\n\n  class Registrar {\n    -factories: Map~string, ProviderFactory~\n    +registerFactory(name, factory)\n    +build(providers)\n    +resolve(name) Provider\n  }\n\n  class Adapter {\n    <<interface>>\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class DefaultAdapter {\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class Provider {\n    <<interface>>\n    +name: string\n    +mapper: ProviderMapper\n    +chatClient: ChatClient\n    +capabilities: ProviderCapabilities\n  }\n\n  class ProviderMapper {\n    <<interface>>\n    +request: RequestMapper\n    +response: ResponseMapper\n    +stream: StreamMapper\n  }\n\n  class ChatClient {\n    <<interface>>\n    +chat(req) Promise~TRes~\n    +streamChat(req) Promise~ReadableStream~\n  }\n\n  class ResponseSessionStore {\n    <<interface>>\n    +get(id) StoredResponseSession\n    +save(session, opts)\n    +resolveChain(id, opts) ResponseSessionSnapshot\n    +delete(id)\n    +close()\n  }\n\n  ApplicationContext --> ResponsesContext : creates\n  ApplicationContext --> ModelResolver\n  ApplicationContext --> Registrar\n  ApplicationContext --> Adapter\n  ApplicationContext --> ResponseSessionStore\n  ResponsesContext --> Provider : uses\n  Provider --> ProviderMapper\n  Provider --> ChatClient\n  Adapter <|.. DefaultAdapter\n  DefaultAdapter --> ProviderMapper : calls\n  DefaultAdapter --> ChatClient : calls\n  DefaultAdapter --> ResponseSessionStore : saves\n```\n\n## Request Flow\n\n```mermaid\nsequenceDiagram\n  actor C as Client (Codex CLI)\n  participant H as handleResponses\n  participant RC as ResponsesContext\n  participant MR as ModelResolver\n  participant SS as SessionStore\n  participant REG as Registrar\n  participant A as DefaultAdapter\n  participant PM as ProviderMapper\n  participant CC as ChatClient\n  participant UP as Upstream API\n\n  C->>H: POST /v1/responses\n  H->>RC: ResponsesContext.create(app, body)\n  activate RC\n    RC->>MR: resolve(model)\n    MR-->>RC: { provider, model }\n    opt previous_response_id\n      RC->>SS: resolveChain(id)\n      SS-->>RC: session snapshot\n    end\n    RC->>REG: resolve(provider)\n    REG-->>RC: Provider instance\n  deactivate RC\n\n  alt stream = true\n    H->>A: adapter.stream(ctx)\n    activate A\n      A->>PM: mapper.request.map(ctx)\n      A->>CC: chatClient.streamChat(req)\n      CC->>UP: POST (SSE)\n      UP-->>CC: SSE chunks\n      A->>A: pipeTransform → ProviderEventToResponse\n      A->>A: pipeTransform → ResponseLog\n      A->>A: pipeTransform → ResponseSessionPersistence\n    deactivate A\n    H->>H: pipeTransform → ResponseSseEncode\n    H-->>C: SSE byte stream\n  else stream = false\n    H->>A: adapter.request(ctx)\n    activate A\n      A->>PM: mapper.request.map(ctx)\n      A->>CC: chatClient.chat(req)\n      CC->>UP: POST\n      UP-->>A: upstream response\n      A->>PM: mapper.response.map(ctx, res)\n      A->>SS: save(session)\n    deactivate A\n    H-->>C: JSON response\n  end\n```\n\n## Stream Pipeline\n\n```mermaid\nflowchart LR\n  subgraph upstream[\"Upstream Provider\"]\n    SSE[\"SSE Chunks\"]\n  end\n\n  subgraph godex[\"GodeX Stream Pipeline\"]\n    T1[\"① ProviderEventToResponse\"]\n    T2[\"② OutputContractValidation\"]\n    T3[\"③ ResponseLog\"]\n    T4[\"④ SessionPersistence\"]\n    T5[\"⑤ CompatibilityLog\"]\n  end\n\n  subgraph server[\"HTTP Response\"]\n    T6[\"⑥ SseEncode\"]\n  end\n\n  subgraph client[\"Client\"]\n    BYTES[\"SSE Bytes\"]\n  end\n\n  SSE -->|pipeThrough| T1\n  T1 -->|map per event| T2\n  T2 -->|validate terminal response| T3\n  T3 -->|log + pass through| T4\n  T4 -->|accumulate + save session| T5\n  T5 -->|emit compatibility diagnostics| T6\n  T6 -->|serialize SSE wire format| BYTES\n\n  style upstream fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n  style godex fill:#0f3460,stroke:#16213e,color:#e0e0e0\n  style server fill:#1c2333,stroke:#16213e,color:#e0e0e0\n  style client fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n```\n\n| Stage | Transformer | Input | Output | Role |\n|-------|------------|-------|--------|------|\n| ① | `ProviderEventToResponseTransformer` | `JsonServerSentEvent` | `ResponseStreamEvent` | Maps upstream SSE chunks via `StreamMapper.map()` |\n| ② | `ResponseOutputContractValidationTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Converts invalid strict downgraded JSON terminals into `response.failed` |\n| ③ | `ResponseLogTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Logs stream events and usage for observability |\n| ④ | `ResponseSessionPersistenceTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Accumulates `StreamState`, saves session on terminal event |\n| ⑤ | `CompatibilityLogTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Emits compatibility diagnostics once per stream |\n| ⑥ | `ResponseSseEncodeTransformer` | `ResponseStreamEvent` | `Uint8Array` | Serializes to `event:` / `data:` wire format |\n\n## Project Structure\n\n```\nsrc/\n├── cli/              Commander CLI (serve, config, init)\n├── config/           godex.yaml schema, env interpolation, defaults\n├── context/          ApplicationContext (DI), ResponsesContext (per-request)\n├── bridge/           Provider-agnostic Responses→Chat planning kernel\n│   ├── compatibility/  CompatibilityPlan and diagnostics planning\n│   ├── tools/          Tool/tool_choice planning and downgrade decisions\n│   └── output/         Output-format contracts and strict JSON validation\n├── adapter/          Adapter interface, DefaultAdapter, stream transformers\n│   ├── mapper/       RequestMapper / ResponseMapper / StreamMapper contracts\n│   └── transformers/ Stream pipeline (map → validate → log → persist → diagnostics)\n├── providers/        Provider registry + builtin factories\n│   ├── deepseek/     DeepSeek Chat Completions bridge provider\n│   └── zhipu/        Zhipu Chat Completions bridge provider\n├── resolver/         ModelResolver (model selector → provider + model)\n├── server/           Bun.serve, routes (/v1/responses, /health, /v1/models)\n├── session/          ResponseSessionStore (Memory + SQLite), chain resolution\n├── error/            GodeXError hierarchy with domain codes\n├── tools/            Built-in function tools (local_shell, shell, apply_patch)\n├── protocol/openai/  OpenAI-compatible type definitions\n├── logger/           Structured JSON logger\n└── e2e/              End-to-end tests with mocked upstream\n```\n\n## Configuration\n\n### godex.yaml\n\n```yaml\nserver:\n  port: 5678\n\ndefault_provider: zhipu\n\nmodels:\n  aliases:\n    \"gpt-4o\": zhipu/glm-4.7   # model name mapping\n    \"*\": zhipu/glm-5.1         # catch-all fallback\n\nproviders:\n  zhipu:\n    api_key: ${ZHIPU_API_KEY}\n    base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  deepseek:\n    api_key: ${DEEPSEEK_API_KEY}\n    base_url: https://api.deepseek.com\n\nsession:\n  backend: sqlite               # or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\ntrace:\n  enabled: true                 # records request/event/usage rows by default\n  path: ./data/trace.db\n  capture_payload: false        # false keeps only payload hash + byte size\n\nlogging:\n  level: info                   # trace | debug | info | warn | error\n```\n\n### Model Selection\n\n```\nmodel: \"gpt-4o\"              → resolved via default_provider model mapping\nmodel: \"zhipu/glm-4.7\"       → explicit provider/model selector\nmodel: \"deepseek/deepseek-v4-pro\" → routes to configured DeepSeek provider\n```\n\n### Health Check\n\n```bash\ncurl http://localhost:5678/health\n# {\"status\":\"ok\",\"providers\":[\"zhipu\",\"deepseek\"],\"unsupported_providers\":[]}\n```\n\n### Adding a Provider\n\nImplement a focused Chat Completions bridge provider in `src/providers/<name>/`:\n\n| Interface | Purpose |\n|-----------|---------|\n| `Provider` | Bundles mapper + chatClient + capabilities |\n| `ProviderMapper` | request / response / stream mapping functions |\n| `ChatClient` | `chat()` and `streamChat()` HTTP calls |\n\nKeep provider-specific files focused on protocol rendering. Shared compatibility decisions belong in `src/bridge/compatibility`, tool availability and `tool_choice` decisions in `src/bridge/tools`, and terminal output checks in `src/bridge/output`.\n\nRegister the factory in `src/providers/builtin.ts`:\n\n```ts\nregistrar.registerFactory(\"myprovider\", (config) =>\n  createMyProvider(config) as Provider<unknown, unknown, unknown>\n);\n```\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload (port 13145)\nbun run test                 # Unit + integration tests\nbun run test:e2e             # E2E tests with mocked upstream\nbun run build                # Build standalone binary for current platform\nbun run check                # typecheck + lint + test\nbun run ci                   # Full CI pipeline\n```\n\n## Publishing\n\n`@ahoo-wang/godex` is a lightweight npm wrapper. Native binaries ship as platform-specific optional dependencies:\n\n```\n@ahoo-wang/godex\n├── @ahoo-wang/godex-darwin-arm64     ← macOS Apple Silicon\n├── @ahoo-wang/godex-darwin-x64       ← macOS Intel\n├── @ahoo-wang/godex-linux-x64        ← Linux x86_64\n├── @ahoo-wang/godex-linux-arm64      ← Linux ARM64\n├── @ahoo-wang/godex-win32-x64        ← Windows x86_64\n└── @ahoo-wang/godex-win32-arm64      ← Windows ARM64\n```\n\n## License\n\n[Apache License 2.0](LICENSE)\n"}, "818bd39bf92e74dddb995c46f47feef9a3339a23": {"t": 1785748588.7649689, "n": 13284, "h": "4a3e2be3ebb02421", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway — translates `/v1/responses` into upstream Chat Completions API calls, connecting Codex, CLI, IDE, and automation tools with any model provider.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n[Getting Started](https://godex.ahoo.me/01-getting-started/overview) · [Architecture](https://godex.ahoo.me/02-architecture/overview) · [Configuration](https://godex.ahoo.me/07-configuration/config-schema) · [Documentation](https://godex.ahoo.me)\n\n</div>\n\n## Features\n\n| | Feature | Description |\n|---|---------|-------------|\n| 🔄 | **Protocol Translation** | Bridges OpenAI Responses API and provider-specific Chat Completions APIs |\n| 🔌 | **Provider-agnostic** | Plugin-based adapter system — add providers by implementing a small set of interfaces |\n| ⚡ | **Streaming-first** | 4-stage `TransformStream` pipeline for low-latency SSE delivery |\n| 💾 | **Session History** | Built-in `previous_response_id` chain resolution (SQLite / in-memory) |\n| 🛡️ | **Structured Errors** | Domain-specific error hierarchy with structured codes and diagnostic context |\n| 🔧 | **Built-in Tools** | `local_shell`, `shell`, `apply_patch` — Codex-compatible function tools |\n| 📦 | **Standalone Binary** | Zero runtime dependencies, 6 platform builds via GitHub Actions |\n\n## Quick Start\n\n```bash\n# Install — no Bun required at runtime\nnpm install -g @ahoo-wang/godex\n\n# Create config interactively\ngodex init\n\n# Start the gateway\ngodex serve\n```\n\nPoint Codex CLI at your GodeX instance:\n\n```bash\nexport OPENAI_BASE_URL=http://localhost:5678/v1\nexport OPENAI_API_KEY=any-value          # not validated by GodeX, must be set\ncodex\n```\n\nOr use the OpenAI SDK:\n\n```ts\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n  baseURL: \"http://localhost:5678/v1\",\n  apiKey: \"any-value\",\n});\n\nconst response = await client.responses.create({\n  model: \"gpt-4o\",          // resolved via models.aliases → zhipu/glm-4.7\n  input: \"Hello!\",\n});\n```\n\n## How It Works\n\n```\nCodex / CLI / IDE\n      │\n      ▼  POST /v1/responses\n┌─────────────────────────────────────────┐\n│              GodeX Gateway              │\n│                                         │\n│  Bun.serve → handleResponses()          │\n│       → ResponsesContext.create()       │\n│           → ModelResolver.resolve()     │\n│           → Registrar.resolve()         │\n│       → DefaultAdapter.stream/request() │\n│           → ProviderMapper.map()        │\n│           → ChatClient.streamChat()     │\n│           → 4-stage TransformStream     │\n│       → Response (JSON or SSE)          │\n└──────────────┬──────────────────────────┘\n               │  Provider Adapter\n               ▼\n┌─────────────────────────────────────────┐\n│       Chat Completions-compatible API   │\n│       (Zhipu, OpenAI, or custom)        │\n└─────────────────────────────────────────┘\n```\n\n## Architecture\n\n```mermaid\nC4Context\n  title GodeX — System Context\n\n  Person(user, \"Developer / Codex CLI\", \"Sends Responses API requests<br/>via the OpenAI-compatible endpoint\")\n  System(godex_svr, \"GodeX Server\", \"Translates Responses API → Chat Completions API<br/>Bun.serve on configurable port\")\n  SystemDb(sessions, \"Session Store\", \"Stores response history for<br/>previous_response_id chain resolution<br/>SQLite (persistent) or In-Memory\")\n  System_Ext(zhipu, \"Zhipu (智谱)\", \"Chat Completions API provider\")\n  System_Ext(openai, \"OpenAI\", \"Chat Completions API provider\")\n  System_Ext(other, \"Custom Provider\", \"Any Chat Completions<br/>compatible backend\")\n\n  Rel(user, godex_svr, \"POST /v1/responses, GET /v1/models, GET /health\", \"HTTP/SSE\")\n  Rel(godex_svr, sessions, \"save / resolve chains\")\n  Rel(godex_svr, zhipu, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, openai, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, other, \"POST /chat/completions\", \"HTTPS\")\n```\n\n## Component Model\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class ApplicationContext {\n    +config: GodeXConfig\n    +logger: Logger\n    +resolver: ModelResolver\n    +registrar: Registrar\n    +adapter: Adapter\n    +sessionStore: ResponseSessionStore\n  }\n\n  class ResponsesContext {\n    +app: ApplicationContext\n    +request: ResponseCreateRequest\n    +session: ResponseSessionSnapshot\n    +resolved: ResolvedModel\n    +provider: Provider\n    +responseId: string\n    +requestId: string\n    +attributes: Map\n    +create(app, body)$ Promise~ResponsesContext~\n  }\n\n  class ModelResolver {\n    -defaultProvider: string\n    -providerConfigs: Record\n    +resolve(model) ResolvedModel\n  }\n\n  class Registrar {\n    -factories: Map~string, ProviderFactory~\n    +registerFactory(name, factory)\n    +build(providers)\n    +resolve(name) Provider\n  }\n\n  class Adapter {\n    <<interface>>\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class DefaultAdapter {\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class Provider {\n    <<interface>>\n    +name: string\n    +mapper: ProviderMapper\n    +chatClient: ChatClient\n    +capabilities: ProviderCapabilities\n  }\n\n  class ProviderMapper {\n    <<interface>>\n    +request: RequestMapper\n    +response: ResponseMapper\n    +stream: StreamMapper\n  }\n\n  class ChatClient {\n    <<interface>>\n    +chat(req) Promise~TRes~\n    +streamChat(req) Promise~ReadableStream~\n  }\n\n  class ResponseSessionStore {\n    <<interface>>\n    +get(id) StoredResponseSession\n    +save(session, opts)\n    +resolveChain(id, opts) ResponseSessionSnapshot\n    +delete(id)\n    +close()\n  }\n\n  ApplicationContext --> ResponsesContext : creates\n  ApplicationContext --> ModelResolver\n  ApplicationContext --> Registrar\n  ApplicationContext --> Adapter\n  ApplicationContext --> ResponseSessionStore\n  ResponsesContext --> Provider : uses\n  Provider --> ProviderMapper\n  Provider --> ChatClient\n  Adapter <|.. DefaultAdapter\n  DefaultAdapter --> ProviderMapper : calls\n  DefaultAdapter --> ChatClient : calls\n  DefaultAdapter --> ResponseSessionStore : saves\n```\n\n## Request Flow\n\n```mermaid\nsequenceDiagram\n  actor C as Client (Codex CLI)\n  participant H as handleResponses\n  participant RC as ResponsesContext\n  participant MR as ModelResolver\n  participant SS as SessionStore\n  participant REG as Registrar\n  participant A as DefaultAdapter\n  participant PM as ProviderMapper\n  participant CC as ChatClient\n  participant UP as Upstream API\n\n  C->>H: POST /v1/responses\n  H->>RC: ResponsesContext.create(app, body)\n  activate RC\n    RC->>MR: resolve(model)\n    MR-->>RC: { provider, model }\n    opt previous_response_id\n      RC->>SS: resolveChain(id)\n      SS-->>RC: session snapshot\n    end\n    RC->>REG: resolve(provider)\n    REG-->>RC: Provider instance\n  deactivate RC\n\n  alt stream = true\n    H->>A: adapter.stream(ctx)\n    activate A\n      A->>PM: mapper.request.map(ctx)\n      A->>CC: chatClient.streamChat(req)\n      CC->>UP: POST (SSE)\n      UP-->>CC: SSE chunks\n      A->>A: pipeTransform → ProviderEventToResponse\n      A->>A: pipeTransform → ResponseLog\n      A->>A: pipeTransform → ResponseSessionPersistence\n    deactivate A\n    H->>H: pipeTransform → ResponseSseEncode\n    H-->>C: SSE byte stream\n  else stream = false\n    H->>A: adapter.request(ctx)\n    activate A\n      A->>PM: mapper.request.map(ctx)\n      A->>CC: chatClient.chat(req)\n      CC->>UP: POST\n      UP-->>A: upstream response\n      A->>PM: mapper.response.map(ctx, res)\n      A->>SS: save(session)\n    deactivate A\n    H-->>C: JSON response\n  end\n```\n\n## Stream Pipeline\n\n```mermaid\nflowchart LR\n  subgraph upstream[\"Upstream Provider\"]\n    SSE[\"SSE Chunks\"]\n  end\n\n  subgraph godex[\"GodeX Stream Pipeline\"]\n    T1[\"① ProviderEventToResponse\"]\n    T2[\"② ResponseLog\"]\n    T3[\"③ SessionPersistence\"]\n  end\n\n  subgraph server[\"HTTP Response\"]\n    T4[\"④ SseEncode\"]\n  end\n\n  subgraph client[\"Client\"]\n    BYTES[\"SSE Bytes\"]\n  end\n\n  SSE -->|pipeThrough| T1\n  T1 -->|map per event| T2\n  T2 -->|log + pass through| T3\n  T3 -->|accumulate + save session| T4\n  T4 -->|serialize SSE wire format| BYTES\n\n  style upstream fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n  style godex fill:#0f3460,stroke:#16213e,color:#e0e0e0\n  style server fill:#1c2333,stroke:#16213e,color:#e0e0e0\n  style client fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n```\n\n| Stage | Transformer | Input | Output | Role |\n|-------|------------|-------|--------|------|\n| ① | `ProviderEventToResponseTransformer` | `JsonServerSentEvent` | `ResponseStreamEvent` | Maps upstream SSE chunks via `StreamMapper.map()` |\n| ② | `ResponseLogTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Logs stream events for observability |\n| ③ | `ResponseSessionPersistenceTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Accumulates `StreamState`, saves session on terminal event |\n| ④ | `ResponseSseEncodeTransformer` | `ResponseStreamEvent` | `Uint8Array` | Serializes to `event:` / `data:` wire format |\n\n## Project Structure\n\n```\nsrc/\n├── cli/              Commander CLI (serve, config, init)\n├── config/           godex.yaml schema, env interpolation, defaults\n├── context/          ApplicationContext (DI), ResponsesContext (per-request)\n├── adapter/          Adapter interface, DefaultAdapter, stream transformers\n│   ├── mapper/       RequestMapper / ResponseMapper / StreamMapper contracts\n│   └── transformers/ 4-stage stream pipeline (map → log → persist → encode)\n├── providers/        Provider registry + builtin factories\n│   └── zhipu/        Reference provider: mapper, chat-client, tools, messages\n├── resolver/         ModelResolver (model selector → provider + model)\n├── server/           Bun.serve, routes (/v1/responses, /health, /v1/models)\n├── session/          ResponseSessionStore (Memory + SQLite), chain resolution\n├── error/            GodeXError hierarchy with domain codes\n├── tools/            Built-in function tools (local_shell, shell, apply_patch)\n├── protocol/openai/  OpenAI-compatible type definitions\n├── logger/           Structured JSON logger\n└── e2e/              End-to-end tests with mocked upstream\n```\n\n## Configuration\n\n### godex.yaml\n\n```yaml\nserver:\n  port: 5678\n\ndefault_provider: zhipu\n\nmodels:\n  aliases:\n    \"gpt-4o\": zhipu/glm-4.7   # model name mapping\n    \"*\": zhipu/glm-5.1         # catch-all fallback\n\nproviders:\n  zhipu:\n    api_key: ${ZHIPU_API_KEY}\n    base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  deepseek:\n    api_key: ${DEEPSEEK_API_KEY}\n    base_url: https://api.deepseek.com\n\nsession:\n  backend: sqlite               # or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\ntrace:\n  enabled: true                 # records request/event/usage rows by default\n  path: ./data/trace.db\n  capture_payload: false        # false keeps only payload hash + byte size\n\nlogging:\n  level: info                   # trace | debug | info | warn | error\n```\n\n### Model Selection\n\n```\nmodel: \"gpt-4o\"              → resolved via default_provider model mapping\nmodel: \"zhipu/glm-4.7\"       → explicit provider/model selector\nmodel: \"deepseek/deepseek-v4-pro\" → routes to configured DeepSeek provider\nmodel: \"openai/gpt-4o\"       → routes to configured openai provider\n```\n\n### Health Check\n\n```bash\ncurl http://localhost:5678/health\n# {\"status\":\"ok\",\"providers\":[\"zhipu\",\"deepseek\"],\"unsupported_providers\":[]}\n```\n\n### Adding a Provider\n\nImplement three interfaces in `src/providers/<name>/`:\n\n| Interface | Purpose |\n|-----------|---------|\n| `Provider` | Bundles mapper + chatClient + capabilities |\n| `ProviderMapper` | request / response / stream mapping functions |\n| `ChatClient` | `chat()` and `streamChat()` HTTP calls |\n\nRegister the factory in `src/providers/builtin.ts`:\n\n```ts\nregistrar.registerFactory(\"myprovider\", (config) =>\n  createMyProvider(config) as Provider<unknown, unknown, unknown>\n);\n```\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload (port 13145)\nbun run test                 # Unit + integration tests\nbun run test:e2e             # E2E tests with mocked upstream\nbun run build                # Build standalone binary for current platform\nbun run check                # typecheck + lint + test\nbun run ci                   # Full CI pipeline\n```\n\n## Publishing\n\n`@ahoo-wang/godex` is a lightweight npm wrapper. Native binaries ship as platform-specific optional dependencies:\n\n```\n@ahoo-wang/godex\n├── @ahoo-wang/godex-darwin-arm64     ← macOS Apple Silicon\n├── @ahoo-wang/godex-darwin-x64       ← macOS Intel\n├── @ahoo-wang/godex-linux-x64        ← Linux x86_64\n├── @ahoo-wang/godex-linux-arm64      ← Linux ARM64\n├── @ahoo-wang/godex-win32-x64        ← Windows x86_64\n└── @ahoo-wang/godex-win32-arm64      ← Windows ARM64\n```\n\n## License\n\n[Apache License 2.0](LICENSE)\n"}, "49620042afbb8aa691fe404cad0446fe9c08b7f7": {"t": 1785748589.8711302, "n": 12928, "h": "0ceba93ee44794d4", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway — translates `/v1/responses` into upstream Chat Completions API calls, connecting Codex, CLI, IDE, and automation tools with any model provider.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n[Getting Started](https://godex.ahoo.me/01-getting-started/overview) · [Architecture](https://godex.ahoo.me/02-architecture/overview) · [Configuration](https://godex.ahoo.me/07-configuration/config-schema) · [Documentation](https://godex.ahoo.me)\n\n</div>\n\n## Features\n\n| | Feature | Description |\n|---|---------|-------------|\n| 🔄 | **Protocol Translation** | Bridges OpenAI Responses API and provider-specific Chat Completions APIs |\n| 🔌 | **Provider-agnostic** | Plugin-based adapter system — add providers by implementing a small set of interfaces |\n| ⚡ | **Streaming-first** | 4-stage `TransformStream` pipeline for low-latency SSE delivery |\n| 💾 | **Session History** | Built-in `previous_response_id` chain resolution (SQLite / in-memory) |\n| 🛡️ | **Structured Errors** | Domain-specific error hierarchy with structured codes and diagnostic context |\n| 🔧 | **Built-in Tools** | `local_shell`, `shell`, `apply_patch` — Codex-compatible function tools |\n| 📦 | **Standalone Binary** | Zero runtime dependencies, 6 platform builds via GitHub Actions |\n\n## Quick Start\n\n```bash\n# Install — no Bun required at runtime\nnpm install -g @ahoo-wang/godex\n\n# Create config interactively\ngodex init\n\n# Start the gateway\ngodex serve\n```\n\nPoint Codex CLI at your GodeX instance:\n\n```bash\nexport OPENAI_BASE_URL=http://localhost:5678/v1\nexport OPENAI_API_KEY=any-value          # not validated by GodeX, must be set\ncodex\n```\n\nOr use the OpenAI SDK:\n\n```ts\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n  baseURL: \"http://localhost:5678/v1\",\n  apiKey: \"any-value\",\n});\n\nconst response = await client.responses.create({\n  model: \"gpt-4o\",          // resolved via models.aliases → zhipu/glm-4.7\n  input: \"Hello!\",\n});\n```\n\n## How It Works\n\n```\nCodex / CLI / IDE\n      │\n      ▼  POST /v1/responses\n┌─────────────────────────────────────────┐\n│              GodeX Gateway              │\n│                                         │\n│  Bun.serve → handleResponses()          │\n│       → ResponsesContext.create()       │\n│           → ModelResolver.resolve()     │\n│           → Registrar.resolve()         │\n│       → DefaultAdapter.stream/request() │\n│           → ProviderMapper.map()        │\n│           → ChatClient.streamChat()     │\n│           → 4-stage TransformStream     │\n│       → Response (JSON or SSE)          │\n└──────────────┬──────────────────────────┘\n               │  Provider Adapter\n               ▼\n┌─────────────────────────────────────────┐\n│       Chat Completions-compatible API   │\n│       (Zhipu, OpenAI, or custom)        │\n└─────────────────────────────────────────┘\n```\n\n## Architecture\n\n```mermaid\nC4Context\n  title GodeX — System Context\n\n  Person(user, \"Developer / Codex CLI\", \"Sends Responses API requests<br/>via the OpenAI-compatible endpoint\")\n  System(godex_svr, \"GodeX Server\", \"Translates Responses API → Chat Completions API<br/>Bun.serve on configurable port\")\n  SystemDb(sessions, \"Session Store\", \"Stores response history for<br/>previous_response_id chain resolution<br/>SQLite (persistent) or In-Memory\")\n  System_Ext(zhipu, \"Zhipu (智谱)\", \"Chat Completions API provider\")\n  System_Ext(openai, \"OpenAI\", \"Chat Completions API provider\")\n  System_Ext(other, \"Custom Provider\", \"Any Chat Completions<br/>compatible backend\")\n\n  Rel(user, godex_svr, \"POST /v1/responses, GET /v1/models, GET /health\", \"HTTP/SSE\")\n  Rel(godex_svr, sessions, \"save / resolve chains\")\n  Rel(godex_svr, zhipu, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, openai, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, other, \"POST /chat/completions\", \"HTTPS\")\n```\n\n## Component Model\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class ApplicationContext {\n    +config: GodeXConfig\n    +logger: Logger\n    +resolver: ModelResolver\n    +registrar: Registrar\n    +adapter: Adapter\n    +sessionStore: ResponseSessionStore\n  }\n\n  class ResponsesContext {\n    +app: ApplicationContext\n    +request: ResponseCreateRequest\n    +session: ResponseSessionSnapshot\n    +resolved: ResolvedModel\n    +provider: Provider\n    +responseId: string\n    +requestId: string\n    +attributes: Map\n    +create(app, body)$ Promise~ResponsesContext~\n  }\n\n  class ModelResolver {\n    -defaultProvider: string\n    -providerConfigs: Record\n    +resolve(model) ResolvedModel\n  }\n\n  class Registrar {\n    -factories: Map~string, ProviderFactory~\n    +registerFactory(name, factory)\n    +build(providers)\n    +resolve(name) Provider\n  }\n\n  class Adapter {\n    <<interface>>\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class DefaultAdapter {\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class Provider {\n    <<interface>>\n    +name: string\n    +mapper: ProviderMapper\n    +chatClient: ChatClient\n    +capabilities: ProviderCapabilities\n  }\n\n  class ProviderMapper {\n    <<interface>>\n    +request: RequestMapper\n    +response: ResponseMapper\n    +stream: StreamMapper\n  }\n\n  class ChatClient {\n    <<interface>>\n    +chat(req) Promise~TRes~\n    +streamChat(req) Promise~ReadableStream~\n  }\n\n  class ResponseSessionStore {\n    <<interface>>\n    +get(id) StoredResponseSession\n    +save(session, opts)\n    +resolveChain(id, opts) ResponseSessionSnapshot\n    +delete(id)\n    +close()\n  }\n\n  ApplicationContext --> ResponsesContext : creates\n  ApplicationContext --> ModelResolver\n  ApplicationContext --> Registrar\n  ApplicationContext --> Adapter\n  ApplicationContext --> ResponseSessionStore\n  ResponsesContext --> Provider : uses\n  Provider --> ProviderMapper\n  Provider --> ChatClient\n  Adapter <|.. DefaultAdapter\n  DefaultAdapter --> ProviderMapper : calls\n  DefaultAdapter --> ChatClient : calls\n  DefaultAdapter --> ResponseSessionStore : saves\n```\n\n## Request Flow\n\n```mermaid\nsequenceDiagram\n  actor C as Client (Codex CLI)\n  participant H as handleResponses\n  participant RC as ResponsesContext\n  participant MR as ModelResolver\n  participant SS as SessionStore\n  participant REG as Registrar\n  participant A as DefaultAdapter\n  participant PM as ProviderMapper\n  participant CC as ChatClient\n  participant UP as Upstream API\n\n  C->>H: POST /v1/responses\n  H->>RC: ResponsesContext.create(app, body)\n  activate RC\n    RC->>MR: resolve(model)\n    MR-->>RC: { provider, model }\n    opt previous_response_id\n      RC->>SS: resolveChain(id)\n      SS-->>RC: session snapshot\n    end\n    RC->>REG: resolve(provider)\n    REG-->>RC: Provider instance\n  deactivate RC\n\n  alt stream = true\n    H->>A: adapter.stream(ctx)\n    activate A\n      A->>PM: mapper.request.map(ctx)\n      A->>CC: chatClient.streamChat(req)\n      CC->>UP: POST (SSE)\n      UP-->>CC: SSE chunks\n      A->>A: pipeTransform → ProviderEventToResponse\n      A->>A: pipeTransform → ResponseLog\n      A->>A: pipeTransform → ResponseSessionPersistence\n    deactivate A\n    H->>H: pipeTransform → ResponseSseEncode\n    H-->>C: SSE byte stream\n  else stream = false\n    H->>A: adapter.request(ctx)\n    activate A\n      A->>PM: mapper.request.map(ctx)\n      A->>CC: chatClient.chat(req)\n      CC->>UP: POST\n      UP-->>A: upstream response\n      A->>PM: mapper.response.map(ctx, res)\n      A->>SS: save(session)\n    deactivate A\n    H-->>C: JSON response\n  end\n```\n\n## Stream Pipeline\n\n```mermaid\nflowchart LR\n  subgraph upstream[\"Upstream Provider\"]\n    SSE[\"SSE Chunks\"]\n  end\n\n  subgraph godex[\"GodeX Stream Pipeline\"]\n    T1[\"① ProviderEventToResponse\"]\n    T2[\"② ResponseLog\"]\n    T3[\"③ SessionPersistence\"]\n  end\n\n  subgraph server[\"HTTP Response\"]\n    T4[\"④ SseEncode\"]\n  end\n\n  subgraph client[\"Client\"]\n    BYTES[\"SSE Bytes\"]\n  end\n\n  SSE -->|pipeThrough| T1\n  T1 -->|map per event| T2\n  T2 -->|log + pass through| T3\n  T3 -->|accumulate + save session| T4\n  T4 -->|serialize SSE wire format| BYTES\n\n  style upstream fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n  style godex fill:#0f3460,stroke:#16213e,color:#e0e0e0\n  style server fill:#1c2333,stroke:#16213e,color:#e0e0e0\n  style client fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n```\n\n| Stage | Transformer | Input | Output | Role |\n|-------|------------|-------|--------|------|\n| ① | `ProviderEventToResponseTransformer` | `JsonServerSentEvent` | `ResponseStreamEvent` | Maps upstream SSE chunks via `StreamMapper.map()` |\n| ② | `ResponseLogTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Logs stream events for observability |\n| ③ | `ResponseSessionPersistenceTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Accumulates `StreamState`, saves session on terminal event |\n| ④ | `ResponseSseEncodeTransformer` | `ResponseStreamEvent` | `Uint8Array` | Serializes to `event:` / `data:` wire format |\n\n## Project Structure\n\n```\nsrc/\n├── cli/              Commander CLI (serve, config, init)\n├── config/           godex.yaml schema, env interpolation, defaults\n├── context/          ApplicationContext (DI), ResponsesContext (per-request)\n├── adapter/          Adapter interface, DefaultAdapter, stream transformers\n│   ├── mapper/       RequestMapper / ResponseMapper / StreamMapper contracts\n│   └── transformers/ 4-stage stream pipeline (map → log → persist → encode)\n├── providers/        Provider registry + builtin factories\n│   └── zhipu/        Reference provider: mapper, chat-client, tools, messages\n├── resolver/         ModelResolver (model selector → provider + model)\n├── server/           Bun.serve, routes (/v1/responses, /health, /v1/models)\n├── session/          ResponseSessionStore (Memory + SQLite), chain resolution\n├── error/            GodeXError hierarchy with domain codes\n├── tools/            Built-in function tools (local_shell, shell, apply_patch)\n├── protocol/openai/  OpenAI-compatible type definitions\n├── logger/           Structured JSON logger\n└── e2e/              End-to-end tests with mocked upstream\n```\n\n## Configuration\n\n### godex.yaml\n\n```yaml\nserver:\n  port: 5678\n\ndefault_provider: zhipu\n\nmodels:\n  aliases:\n    \"gpt-4o\": zhipu/glm-4.7   # model name mapping\n    \"*\": zhipu/glm-5.1         # catch-all fallback\n\nproviders:\n  zhipu:\n    api_key: ${ZHIPU_API_KEY}\n    base_url: https://open.bigmodel.cn/api/coding/paas/v4\n\nsession:\n  backend: sqlite               # or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info                   # trace | debug | info | warn | error\n```\n\n### Model Selection\n\n```\nmodel: \"gpt-4o\"              → resolved via default_provider model mapping\nmodel: \"zhipu/glm-4.7\"       → explicit provider/model selector\nmodel: \"openai/gpt-4o\"       → routes to configured openai provider\n```\n\n### Health Check\n\n```bash\ncurl http://localhost:5678/health\n# {\"status\":\"ok\",\"providers\":[\"zhipu\"],\"unsupported_providers\":[]}\n```\n\n### Adding a Provider\n\nImplement three interfaces in `src/providers/<name>/`:\n\n| Interface | Purpose |\n|-----------|---------|\n| `Provider` | Bundles mapper + chatClient + capabilities |\n| `ProviderMapper` | request / response / stream mapping functions |\n| `ChatClient` | `chat()` and `streamChat()` HTTP calls |\n\nRegister the factory in `src/providers/builtin.ts`:\n\n```ts\nregistrar.registerFactory(\"myprovider\", (config) =>\n  createMyProvider(config) as Provider<unknown, unknown, unknown>\n);\n```\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload (port 13145)\nbun run test                 # Unit + integration tests\nbun run test:e2e             # E2E tests with mocked upstream\nbun run build                # Build standalone binary for current platform\nbun run check                # typecheck + lint + test\nbun run ci                   # Full CI pipeline\n```\n\n## Publishing\n\n`@ahoo-wang/godex` is a lightweight npm wrapper. Native binaries ship as platform-specific optional dependencies:\n\n```\n@ahoo-wang/godex\n├── @ahoo-wang/godex-darwin-arm64     ← macOS Apple Silicon\n├── @ahoo-wang/godex-darwin-x64       ← macOS Intel\n├── @ahoo-wang/godex-linux-x64        ← Linux x86_64\n├── @ahoo-wang/godex-linux-arm64      ← Linux ARM64\n├── @ahoo-wang/godex-win32-x64        ← Windows x86_64\n└── @ahoo-wang/godex-win32-arm64      ← Windows ARM64\n```\n\n## License\n\n[Apache License 2.0](LICENSE)\n"}, "84800165cfcb9a1ebf98bf398850bb4ad8db8e5d": {"t": 1785748591.6599681, "n": 12925, "h": "ddf92e9847779922", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway — translates `/v1/responses` into upstream Chat Completions API calls, connecting Codex, CLI, IDE, and automation tools with any model provider.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n[Getting Started](https://godex.ahoo.me/01-getting-started/overview) · [Architecture](https://godex.ahoo.me/02-architecture/overview) · [Configuration](https://godex.ahoo.me/07-configuration/config-schema) · [Documentation](https://godex.ahoo.me)\n\n</div>\n\n## Features\n\n| | Feature | Description |\n|---|---------|-------------|\n| 🔄 | **Protocol Translation** | Bridges OpenAI Responses API and provider-specific Chat Completions APIs |\n| 🔌 | **Provider-agnostic** | Plugin-based adapter system — add providers by implementing a small set of interfaces |\n| ⚡ | **Streaming-first** | 4-stage `TransformStream` pipeline for low-latency SSE delivery |\n| 💾 | **Session History** | Built-in `previous_response_id` chain resolution (SQLite / in-memory) |\n| 🛡️ | **Structured Errors** | Domain-specific error hierarchy with structured codes and diagnostic context |\n| 🔧 | **Built-in Tools** | `local_shell`, `shell`, `apply_patch` — Codex-compatible function tools |\n| 📦 | **Standalone Binary** | Zero runtime dependencies, 6 platform builds via GitHub Actions |\n\n## Quick Start\n\n```bash\n# Install — no Bun required at runtime\nnpm install -g @ahoo-wang/godex\n\n# Create config interactively\ngodex init\n\n# Start the gateway\ngodex serve\n```\n\nPoint Codex CLI at your GodeX instance:\n\n```bash\nexport OPENAI_BASE_URL=http://localhost:5678/v1\nexport OPENAI_API_KEY=any-value          # not validated by GodeX, must be set\ncodex\n```\n\nOr use the OpenAI SDK:\n\n```ts\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n  baseURL: \"http://localhost:5678/v1\",\n  apiKey: \"any-value\",\n});\n\nconst response = await client.responses.create({\n  model: \"gpt-4o\",          // mapped to glm-4.7 via godex.yaml models table\n  input: \"Hello!\",\n});\n```\n\n## How It Works\n\n```\nCodex / CLI / IDE\n      │\n      ▼  POST /v1/responses\n┌─────────────────────────────────────────┐\n│              GodeX Gateway              │\n│                                         │\n│  Bun.serve → handleResponses()          │\n│       → ResponsesContext.create()       │\n│           → ModelResolver.resolve()     │\n│           → Registrar.resolve()         │\n│       → DefaultAdapter.stream/request() │\n│           → ProviderMapper.map()        │\n│           → ChatClient.streamChat()     │\n│           → 4-stage TransformStream     │\n│       → Response (JSON or SSE)          │\n└──────────────┬──────────────────────────┘\n               │  Provider Adapter\n               ▼\n┌─────────────────────────────────────────┐\n│       Chat Completions-compatible API   │\n│       (Zhipu, OpenAI, or custom)        │\n└─────────────────────────────────────────┘\n```\n\n## Architecture\n\n```mermaid\nC4Context\n  title GodeX — System Context\n\n  Person(user, \"Developer / Codex CLI\", \"Sends Responses API requests<br/>via the OpenAI-compatible endpoint\")\n  System(godex_svr, \"GodeX Server\", \"Translates Responses API → Chat Completions API<br/>Bun.serve on configurable port\")\n  SystemDb(sessions, \"Session Store\", \"Stores response history for<br/>previous_response_id chain resolution<br/>SQLite (persistent) or In-Memory\")\n  System_Ext(zhipu, \"Zhipu (智谱)\", \"Chat Completions API provider\")\n  System_Ext(openai, \"OpenAI\", \"Chat Completions API provider\")\n  System_Ext(other, \"Custom Provider\", \"Any Chat Completions<br/>compatible backend\")\n\n  Rel(user, godex_svr, \"POST /v1/responses, GET /v1/models, GET /health\", \"HTTP/SSE\")\n  Rel(godex_svr, sessions, \"save / resolve chains\")\n  Rel(godex_svr, zhipu, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, openai, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, other, \"POST /chat/completions\", \"HTTPS\")\n```\n\n## Component Model\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class ApplicationContext {\n    +config: GodeXConfig\n    +logger: Logger\n    +resolver: ModelResolver\n    +registrar: Registrar\n    +adapter: Adapter\n    +sessionStore: ResponseSessionStore\n  }\n\n  class ResponsesContext {\n    +app: ApplicationContext\n    +request: ResponseCreateRequest\n    +session: ResponseSessionSnapshot\n    +resolved: ResolvedModel\n    +provider: Provider\n    +responseId: string\n    +requestId: string\n    +attributes: Map\n    +create(app, body)$ Promise~ResponsesContext~\n  }\n\n  class ModelResolver {\n    -defaultProvider: string\n    -providerConfigs: Record\n    +resolve(model) ResolvedModel\n  }\n\n  class Registrar {\n    -factories: Map~string, ProviderFactory~\n    +registerFactory(name, factory)\n    +build(providers)\n    +resolve(name) Provider\n  }\n\n  class Adapter {\n    <<interface>>\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class DefaultAdapter {\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class Provider {\n    <<interface>>\n    +name: string\n    +mapper: ProviderMapper\n    +chatClient: ChatClient\n    +capabilities: ProviderCapabilities\n  }\n\n  class ProviderMapper {\n    <<interface>>\n    +request: RequestMapper\n    +response: ResponseMapper\n    +stream: StreamMapper\n  }\n\n  class ChatClient {\n    <<interface>>\n    +chat(req) Promise~TRes~\n    +streamChat(req) Promise~ReadableStream~\n  }\n\n  class ResponseSessionStore {\n    <<interface>>\n    +get(id) StoredResponseSession\n    +save(session, opts)\n    +resolveChain(id, opts) ResponseSessionSnapshot\n    +delete(id)\n    +close()\n  }\n\n  ApplicationContext --> ResponsesContext : creates\n  ApplicationContext --> ModelResolver\n  ApplicationContext --> Registrar\n  ApplicationContext --> Adapter\n  ApplicationContext --> ResponseSessionStore\n  ResponsesContext --> Provider : uses\n  Provider --> ProviderMapper\n  Provider --> ChatClient\n  Adapter <|.. DefaultAdapter\n  DefaultAdapter --> ProviderMapper : calls\n  DefaultAdapter --> ChatClient : calls\n  DefaultAdapter --> ResponseSessionStore : saves\n```\n\n## Request Flow\n\n```mermaid\nsequenceDiagram\n  actor C as Client (Codex CLI)\n  participant H as handleResponses\n  participant RC as ResponsesContext\n  participant MR as ModelResolver\n  participant SS as SessionStore\n  participant REG as Registrar\n  participant A as DefaultAdapter\n  participant PM as ProviderMapper\n  participant CC as ChatClient\n  participant UP as Upstream API\n\n  C->>H: POST /v1/responses\n  H->>RC: ResponsesContext.create(app, body)\n  activate RC\n    RC->>MR: resolve(model)\n    MR-->>RC: { provider, model }\n    opt previous_response_id\n      RC->>SS: resolveChain(id)\n      SS-->>RC: session snapshot\n    end\n    RC->>REG: resolve(provider)\n    REG-->>RC: Provider instance\n  deactivate RC\n\n  alt stream = true\n    H->>A: adapter.stream(ctx)\n    activate A\n      A->>PM: mapper.request.map(ctx)\n      A->>CC: chatClient.streamChat(req)\n      CC->>UP: POST (SSE)\n      UP-->>CC: SSE chunks\n      A->>A: pipeTransform → ProviderEventToResponse\n      A->>A: pipeTransform → ResponseLog\n      A->>A: pipeTransform → ResponseSessionPersistence\n    deactivate A\n    H->>H: pipeTransform → ResponseSseEncode\n    H-->>C: SSE byte stream\n  else stream = false\n    H->>A: adapter.request(ctx)\n    activate A\n      A->>PM: mapper.request.map(ctx)\n      A->>CC: chatClient.chat(req)\n      CC->>UP: POST\n      UP-->>A: upstream response\n      A->>PM: mapper.response.map(ctx, res)\n      A->>SS: save(session)\n    deactivate A\n    H-->>C: JSON response\n  end\n```\n\n## Stream Pipeline\n\n```mermaid\nflowchart LR\n  subgraph upstream[\"Upstream Provider\"]\n    SSE[\"SSE Chunks\"]\n  end\n\n  subgraph godex[\"GodeX Stream Pipeline\"]\n    T1[\"① ProviderEventToResponse\"]\n    T2[\"② ResponseLog\"]\n    T3[\"③ SessionPersistence\"]\n  end\n\n  subgraph server[\"HTTP Response\"]\n    T4[\"④ SseEncode\"]\n  end\n\n  subgraph client[\"Client\"]\n    BYTES[\"SSE Bytes\"]\n  end\n\n  SSE -->|pipeThrough| T1\n  T1 -->|map per event| T2\n  T2 -->|log + pass through| T3\n  T3 -->|accumulate + save session| T4\n  T4 -->|serialize SSE wire format| BYTES\n\n  style upstream fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n  style godex fill:#0f3460,stroke:#16213e,color:#e0e0e0\n  style server fill:#1c2333,stroke:#16213e,color:#e0e0e0\n  style client fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n```\n\n| Stage | Transformer | Input | Output | Role |\n|-------|------------|-------|--------|------|\n| ① | `ProviderEventToResponseTransformer` | `JsonServerSentEvent` | `ResponseStreamEvent` | Maps upstream SSE chunks via `StreamMapper.map()` |\n| ② | `ResponseLogTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Logs stream events for observability |\n| ③ | `ResponseSessionPersistenceTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Accumulates `StreamState`, saves session on terminal event |\n| ④ | `ResponseSseEncodeTransformer` | `ResponseStreamEvent` | `Uint8Array` | Serializes to `event:` / `data:` wire format |\n\n## Project Structure\n\n```\nsrc/\n├── cli/              Commander CLI (serve, config, init)\n├── config/           godex.yaml schema, env interpolation, defaults\n├── context/          ApplicationContext (DI), ResponsesContext (per-request)\n├── adapter/          Adapter interface, DefaultAdapter, stream transformers\n│   ├── mapper/       RequestMapper / ResponseMapper / StreamMapper contracts\n│   └── transformers/ 4-stage stream pipeline (map → log → persist → encode)\n├── providers/        Provider registry + builtin factories\n│   └── zhipu/        Reference provider: mapper, chat-client, tools, messages\n├── resolver/         ModelResolver (model selector → provider + model)\n├── server/           Bun.serve, routes (/v1/responses, /health, /v1/models)\n├── session/          ResponseSessionStore (Memory + SQLite), chain resolution\n├── error/            GodeXError hierarchy with domain codes\n├── tools/            Built-in function tools (local_shell, shell, apply_patch)\n├── protocol/openai/  OpenAI-compatible type definitions\n├── logger/           Structured JSON logger\n└── e2e/              End-to-end tests with mocked upstream\n```\n\n## Configuration\n\n### godex.yaml\n\n```yaml\nserver:\n  port: 5678\n\ndefault_provider: zhipu\n\nproviders:\n  zhipu:\n    api_key: ${ZHIPU_API_KEY}\n    base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    models:\n      \"gpt-4o\": glm-4.7         # model name mapping\n      \"*\": glm-5.1              # catch-all fallback\n\nsession:\n  backend: sqlite               # or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info                   # trace | debug | info | warn | error\n```\n\n### Model Selection\n\n```\nmodel: \"gpt-4o\"              → resolved via default_provider model mapping\nmodel: \"zhipu/glm-4.7\"       → explicit provider/model selector\nmodel: \"openai/gpt-4o\"       → routes to configured openai provider\n```\n\n### Health Check\n\n```bash\ncurl http://localhost:5678/health\n# {\"status\":\"ok\",\"providers\":[\"zhipu\"],\"unsupported_providers\":[]}\n```\n\n### Adding a Provider\n\nImplement three interfaces in `src/providers/<name>/`:\n\n| Interface | Purpose |\n|-----------|---------|\n| `Provider` | Bundles mapper + chatClient + capabilities |\n| `ProviderMapper` | request / response / stream mapping functions |\n| `ChatClient` | `chat()` and `streamChat()` HTTP calls |\n\nRegister the factory in `src/providers/builtin.ts`:\n\n```ts\nregistrar.registerFactory(\"myprovider\", (config) =>\n  createMyProvider(config) as Provider<unknown, unknown, unknown>\n);\n```\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload (port 13145)\nbun run test                 # Unit + integration tests\nbun run test:e2e             # E2E tests with mocked upstream\nbun run build                # Build standalone binary for current platform\nbun run check                # typecheck + lint + test\nbun run ci                   # Full CI pipeline\n```\n\n## Publishing\n\n`@ahoo-wang/godex` is a lightweight npm wrapper. Native binaries ship as platform-specific optional dependencies:\n\n```\n@ahoo-wang/godex\n├── @ahoo-wang/godex-darwin-arm64     ← macOS Apple Silicon\n├── @ahoo-wang/godex-darwin-x64       ← macOS Intel\n├── @ahoo-wang/godex-linux-x64        ← Linux x86_64\n├── @ahoo-wang/godex-linux-arm64      ← Linux ARM64\n├── @ahoo-wang/godex-win32-x64        ← Windows x86_64\n└── @ahoo-wang/godex-win32-arm64      ← Windows ARM64\n```\n\n## License\n\n[Apache License 2.0](LICENSE)\n"}, "b04d6a3e641ed72890736e63efae173b348a4110": {"t": 1785748593.4695933, "n": 9796, "h": "ea631e6b31a6ba9d", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway — translates `/v1/responses` into upstream Chat Completions API calls, connecting Codex, CLI, IDE, and automation tools with any model provider.\n\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n[Getting Started](https://godex.ahoo.me/01-getting-started/overview) · [Architecture](https://godex.ahoo.me/02-architecture/overview) · [Configuration](https://godex.ahoo.me/07-configuration/config-schema) · [API Reference](https://godex.ahoo.me/01-getting-started/quick-reference) · [Documentation](https://godex.ahoo.me)\n\n</div>\n\n---\n\n## Quick Start\n\n```bash\n# Install — no Bun required at runtime\nnpm install -g @ahoo-wang/godex\n\n# Create config interactively\ngodex init\n\n# Start the gateway\ngodex serve\n```\n\nPoint Codex CLI at your GodeX instance:\n\n```bash\nexport OPENAI_BASE_URL=http://localhost:5678/v1\nexport OPENAI_API_KEY=any-value          # not validated by GodeX, must be set\ncodex\n```\n\nOr use the OpenAI SDK:\n\n```ts\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n  baseURL: \"http://localhost:5678/v1\",\n  apiKey: \"any-value\",\n});\n\nconst response = await client.responses.create({\n  model: \"gpt-4o\",          // mapped to glm-4.7 via godex.yaml models table\n  input: \"Hello!\",\n});\n```\n\n## How It Works\n\n```\nCodex / CLI / IDE\n      │\n      ▼  POST /v1/responses\n┌─────────────────┐\n│   GodeX Gateway │\n└────────┬────────┘\n         │  Provider Adapter\n         ▼\n┌─────────────────────────┐\n│  Chat Completions API   │\n│  (any compatible model) │\n└─────────────────────────┘\n```\n\n## Architecture\n\n```mermaid\nC4Context\n  title GodeX — System Context\n\n  Person(user, \"Developer / Codex CLI\", \"Sends Responses API requests<br/>via the OpenAI-compatible endpoint\")\n  System(godex_svr, \"GodeX Server\", \"Translates Responses API → Chat Completions API<br/>Bun HTTP server on configurable port\")\n  SystemDb(sessions, \"Session Store\", \"Stores response history for<br/>previous_response_id chain resolution<br/>SQLite (persistent) or In-Memory\")\n  System_Ext(zhipu, \"Zhipu (智谱)\", \"Chat Completions API provider\")\n  System_Ext(openai, \"OpenAI\", \"Chat Completions API provider\")\n  System_Ext(other, \"Custom Provider\", \"Any Chat Completions<br/>compatible backend\")\n\n  Rel(user, godex_svr, \"POST /v1/responses, GET /v1/models, GET /health\", \"HTTP/SSE\")\n  Rel(godex_svr, sessions, \"save / resolve chains\")\n  Rel(godex_svr, zhipu, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, openai, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, other, \"POST /chat/completions\", \"HTTPS\")\n```\n\n## Request Flow\n\n```mermaid\nsequenceDiagram\n  actor C as Client (Codex CLI)\n  participant R as Router\n  participant AC as ApplicationContext\n  participant RC as ResponsesContext\n  participant MR as ModelResolver\n  participant SS as SessionStore\n  participant REG as Registrar\n  participant A as Adapter (DefaultAdapter)\n  participant PM as ProviderMapper\n  participant CC as ChatClient\n  participant UP as Upstream API\n\n  C->>R: POST /v1/responses\n  R->>RC: ResponsesContext.create(app, body)\n\n  activate RC\n    RC->>MR: resolve(model)\n    MR-->>RC: { provider, model }\n    RC->>RC: validate provider config\n\n    opt previous_response_id\n      RC->>SS: resolveChain(id)\n      SS-->>RC: session snapshot\n    end\n\n    RC->>REG: resolve(provider)\n    REG-->>RC: Provider instance\n  deactivate RC\n\n  alt stream = true\n    R->>A: adapter.stream(ctx)\n    activate A\n      A->>PM: request.map(ctx)\n      PM-->>A: upstream request\n      A->>CC: streamChat(req)\n      CC->>UP: POST (SSE)\n      UP-->>CC: SSE chunks\n      CC-->>A: ReadableStream<SSE>\n      A->>A: pipeTransform → ProviderEventToResponseTransformer\n      A->>A: pipeTransform → ResponseSessionPersistenceTransformer\n      A-->>R: ReadableStream<ResponseStreamEvent>\n    deactivate A\n    R->>R: pipeTransform → ResponseSseEncodeTransformer\n    R-->>C: SSE byte stream\n  else stream = false\n    R->>A: adapter.request(ctx)\n    activate A\n      A->>PM: request.map(ctx)\n      PM-->>A: upstream request\n      A->>CC: chat(req)\n      CC->>UP: POST\n      UP-->>CC: JSON response\n      CC-->>A: upstream response\n      A->>PM: response.map(ctx, res)\n      PM-->>A: ResponseObject\n      A->>SS: save(session)\n      A-->>R: ResponseObject\n    deactivate A\n    R-->>C: JSON response\n  end\n```\n\n## Stream Pipeline\n\n```mermaid\nflowchart LR\n  subgraph upstream[\"Upstream Provider\"]\n    SSE[\"SSE Chunks<br/>(JsonServerSentEvent)\"]\n  end\n\n  subgraph godex[\"GodeX Stream Pipeline\"]\n    T1[\"ProviderEventTo<br/>ResponseTransformer\"]\n    T2[\"ResponseSession<br/>PersistenceTransformer\"]\n    T3[\"ResponseSse<br/>EncodeTransformer\"]\n  end\n\n  subgraph client[\"Client\"]\n    BYTES[\"SSE Bytes<br/>(text/event-stream)\"]\n  end\n\n  SSE -->|\"pipeThrough(TransformStream)\"| T1\n  T1 -->|\"per-event map()<br/>SSE chunk → ResponseStreamEvent[]\"| T2\n  T2 -->|\"accumulate StreamState<br/>intercept terminal event<br/>buildResponseObject()<br/>save session\"| T3\n  T3 -->|\"serialize to SSE wire format<br/>event: xxx\\ndata: {...}\\n\\n\"| BYTES\n\n  style upstream fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n  style godex fill:#0f3460,stroke:#16213e,color:#e0e0e0\n  style client fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n```\n\n| Stage | Transformer | Input | Output | Side Effects |\n|-------|------------|-------|--------|-------------|\n| 1 | `ProviderEventToResponseTransformer` | `JsonServerSentEvent<TChunk>` | `ResponseStreamEvent` | Calls `StreamMapper.map()` per event |\n| 2 | `ResponseSessionPersistenceTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Accumulates `StreamState`, on terminal event calls `buildResponseObject()` + saves session |\n| 3 | `ResponseSseEncodeTransformer` | `ResponseStreamEvent` | `Uint8Array` (SSE wire format) | Serializes to `event:` / `data:` lines |\n\n## Project Structure\n\n```\nsrc/\n├── cli/              Commander CLI (serve, config check, init)\n├── config/           godex.yaml schema, env interpolation, defaults\n├── context/          ApplicationContext (DI container), ResponsesContext (per-request)\n├── adapter/          Adapter interface, DefaultAdapter, stream transformers\n│   ├── mapper/       RequestMapper / ResponseMapper / StreamMapper contracts\n│   └── transformers/ ProviderEvent → Response → SSE encode pipeline\n├── providers/        Provider registry + builtin factories\n│   └── zhipu/        Reference provider: mapper, chat-client, tools, messages\n├── resolver/         ModelResolver (model selector → provider + model)\n├── server/           Bun HTTP server, Router, routes (/v1/responses, /health, /v1/models)\n├── session/          ResponseSessionStore (Memory + SQLite), chain resolution\n├── error/            GodeXError hierarchy with domain codes\n├── protocol/openai/  OpenAI-compatible type definitions\n├── logger/           Structured JSON logger\n└── e2e/              End-to-end tests with mocked upstream\n```\n\n## Configuration\n\n### godex.yaml\n\n```yaml\nserver:\n  port: 5678\n\ndefault_provider: zhipu\n\nproviders:\n  zhipu:\n    api_key: ${ZHIPU_API_KEY}\n    base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    models:\n      \"gpt-4o\": glm-4.7         # model name mapping\n      \"*\": glm-5.1              # catch-all fallback\n\nsession:\n  backend: sqlite               # or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info                   # trace | debug | info | warn | error\n```\n\n### Model Selection\n\n```\nmodel: \"gpt-4o\"              → resolved via default_provider model mapping\nmodel: \"zhipu/glm-4.7\"       → explicit provider/model selector\nmodel: \"openai/gpt-4o\"       → routes to configured openai provider\n```\n\n### Adding a Provider\n\nImplement these interfaces in `src/providers/<name>/`:\n\n| Interface | Purpose |\n|-----------|---------|\n| `Provider<TReq, TRes, TChunk>` | Bundles mapper + chatClient + capabilities |\n| `ProviderMapper<TReq, TRes, TChunk>` | request / response / stream mapping functions |\n| `ChatClient<TReq, TRes, TChunk>` | `chat()` and `streamChat()` HTTP calls |\n\nRegister the factory in `src/providers/builtin.ts`:\n\n```ts\nregistrar.registerFactory(\"myprovider\", (config) =>\n  createMyProvider(config) as Provider<unknown, unknown, unknown>\n);\n```\n\n## Commands\n\n```bash\nbun run dev          # Hot-reload dev server on port 13145\nbun run build        # Compile native binary for current platform\nbun run compile:all  # Cross-compile all 6 platforms locally\nbun run test         # Unit + integration tests\nbun run test:e2e     # E2E with mocked upstream\nbun run typecheck    # tsc --noEmit\nbun run lint         # Biome check\nbun run ci           # Full CI pipeline\n```\n\n## Publishing\n\nThe main `@ahoo-wang/godex` npm package is a lightweight shell. Native binaries are shipped as platform-specific optional dependencies:\n\n```\n@ahoo-wang/godex (wrapper package, 0 runtime deps)\n├── engines: { node: \">=18.0.0\" }    ← only for postinstall\n├── postinstall: scripts/install.cjs   ← detects platform, links binary\n└── optionalDependencies:\n    ├── @ahoo-wang/godex-darwin-arm64           ← macOS Apple Silicon\n    ├── @ahoo-wang/godex-darwin-x64             ← macOS Intel\n    ├── @ahoo-wang/godex-linux-x64              ← Linux x86_64\n    ├── @ahoo-wang/godex-linux-arm64            ← Linux ARM64\n    ├── @ahoo-wang/godex-win32-x64              ← Windows x86_64\n    └── @ahoo-wang/godex-win32-arm64            ← Windows ARM64\n```\n\n## License\n\n[Apache License 2.0](LICENSE)\n"}, "29cb3a87490dc075b5d879b8e171099c84e8981f": {"t": 1785748594.8727396, "n": 14090, "h": "48b00c3034ad1e39", "c": "# GodeX\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway — translates `/v1/responses` into upstream Chat Completions API calls, connecting Codex, CLI, IDE, and automation tools with any model provider.\n\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n## Architecture\n\n```mermaid\nC4Context\n  title GodeX — System Context\n\n  Person(user, \"Developer / Codex CLI\", \"Sends Responses API requests<br/>via the OpenAI-compatible endpoint\")\n  System(godex_svr, \"GodeX Server\", \"Translates Responses API → Chat Completions API<br/>Bun HTTP server on configurable port\")\n  SystemDb(sessions, \"Session Store\", \"Stores response history for<br/>previous_response_id chain resolution<br/>SQLite (persistent) or In-Memory\")\n  System_Ext(zhipu, \"Zhipu (智谱)\", \"Chat Completions API provider\")\n  System_Ext(openai, \"OpenAI\", \"Chat Completions API provider\")\n  System_Ext(other, \"Custom Provider\", \"Any Chat Completions<br/>compatible backend\")\n\n  Rel(user, godex_svr, \"POST /v1/responses, GET /v1/models, GET /health\", \"HTTP/SSE\")\n  Rel(godex_svr, sessions, \"save / resolve chains\")\n  Rel(godex_svr, zhipu, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, openai, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, other, \"POST /chat/completions\", \"HTTPS\")\n```\n\n## Request Flow\n\n```mermaid\nsequenceDiagram\n  actor C as Client (Codex CLI)\n  participant R as Router\n  participant AC as ApplicationContext\n  participant RC as ResponsesContext\n  participant MR as ModelResolver\n  participant SS as SessionStore\n  participant REG as Registrar\n  participant A as Adapter (DefaultAdapter)\n  participant PM as ProviderMapper\n  participant CC as ChatClient\n  participant UP as Upstream API\n\n  C->>R: POST /v1/responses\n  R->>RC: ResponsesContext.create(app, body)\n\n  activate RC\n    RC->>MR: resolve(model)\n    MR-->>RC: { provider, model }\n    RC->>RC: validate provider config\n\n    opt previous_response_id\n      RC->>SS: resolveChain(id)\n      SS-->>RC: session snapshot\n    end\n\n    RC->>REG: resolve(provider)\n    REG-->>RC: Provider instance\n  deactivate RC\n\n  alt stream = true\n    R->>A: adapter.stream(ctx)\n    activate A\n      A->>PM: request.map(ctx)\n      PM-->>A: upstream request\n      A->>CC: streamChat(req)\n      CC->>UP: POST (SSE)\n      UP-->>CC: SSE chunks\n      CC-->>A: ReadableStream<SSE>\n      A->>A: pipeTransform → ProviderEventToResponseTransformer\n      A->>A: pipeTransform → ResponseSessionPersistenceTransformer\n      A-->>R: ReadableStream<ResponseStreamEvent>\n    deactivate A\n    R->>R: pipeTransform → ResponseSseEncodeTransformer\n    R-->>C: SSE byte stream\n  else stream = false\n    R->>A: adapter.request(ctx)\n    activate A\n      A->>PM: request.map(ctx)\n      PM-->>A: upstream request\n      A->>CC: chat(req)\n      CC->>UP: POST\n      UP-->>CC: JSON response\n      CC-->>A: upstream response\n      A->>PM: response.map(ctx, res)\n      PM-->>A: ResponseObject\n      A->>SS: save(session)\n      A-->>R: ResponseObject\n    deactivate A\n    R-->>C: JSON response\n  end\n```\n\n## Component Model\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class ApplicationContext {\n    +config: GodeXConfig\n    +logger: Logger\n    +resolver: ModelResolver\n    +registrar: Registrar\n    +adapter: Adapter\n    +sessionStore: ResponseSessionStore\n  }\n\n  class ResponsesContext {\n    +app: ApplicationContext\n    +request: ResponseCreateRequest\n    +session: ResponseSessionSnapshot\n    +resolved: ResolvedModel\n    +provider: Provider\n    +responseId: string\n    +requestId: string\n    +logger: Logger\n    +create(app, body)$ Promise~ResponsesContext~\n  }\n\n  class ModelResolver {\n    -defaultProvider: string\n    -providerConfigs: Record\n    +resolve(model) ResolvedModel\n  }\n\n  class Registrar {\n    -factories: Map~string, ProviderFactory~\n    +registerFactory(name, factory)\n    +build(providers)\n    +resolve(name) Provider\n    +list() string[]\n  }\n\n  class Adapter {\n    <<interface>>\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class DefaultAdapter {\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class Provider {\n    <<interface>>\n    +name: string\n    +mapper: ProviderMapper\n    +chatClient: ChatClient\n    +capabilities: ProviderCapabilities\n  }\n\n  class ProviderMapper {\n    <<interface>>\n    +request: RequestMapper\n    +response: ResponseMapper\n    +stream: StreamMapper\n  }\n\n  class ChatClient {\n    <<interface>>\n    +chat(req) Promise~TRes~\n    +streamChat(req) Promise~ReadableStream~\n  }\n\n  class RequestMapper {\n    <<interface>>\n    +map(ctx) TReq\n  }\n\n  class ResponseMapper {\n    <<interface>>\n    +map(ctx, result) ResponseObject\n  }\n\n  class StreamMapper {\n    <<interface>>\n    +map(ctx, event) ResponseStreamEvent[]\n    +buildResponseObject(ctx, state) ResponseObject\n  }\n\n  class ResponseSessionStore {\n    <<interface>>\n    +get(id) StoredResponseSession\n    +save(session, opts)\n    +resolveChain(id, opts) ResponseSessionSnapshot\n    +delete(id)\n    +close()\n  }\n\n  class Router {\n    -routes: Route[]\n    +register(route)\n    +dispatch(req) Promise~Response~\n  }\n\n  ApplicationContext --> ResponsesContext : creates\n  ApplicationContext --> ModelResolver\n  ApplicationContext --> Registrar\n  ApplicationContext --> Adapter\n  ApplicationContext --> ResponseSessionStore\n  ResponsesContext --> Provider : uses\n  Provider --> ProviderMapper\n  Provider --> ChatClient\n  ProviderMapper --> RequestMapper\n  ProviderMapper --> ResponseMapper\n  ProviderMapper --> StreamMapper\n  Adapter <|.. DefaultAdapter\n  DefaultAdapter --> ProviderMapper : calls\n  DefaultAdapter --> ChatClient : calls\n  DefaultAdapter --> ResponseSessionStore : saves\n  Router --> ResponsesContext : dispatches to\n```\n\n## Stream Pipeline\n\n```mermaid\nflowchart LR\n  subgraph upstream[\"Upstream Provider\"]\n    SSE[\"SSE Chunks<br/>(JsonServerSentEvent)\"]\n  end\n\n  subgraph godex[\"GodeX Stream Pipeline\"]\n    T1[\"ProviderEventTo<br/>ResponseTransformer\"]\n    T2[\"ResponseSession<br/>PersistenceTransformer\"]\n    T3[\"ResponseSse<br/>EncodeTransformer\"]\n  end\n\n  subgraph client[\"Client\"]\n    BYTES[\"SSE Bytes<br/>(text/event-stream)\"]\n  end\n\n  SSE -->|\"pipeThrough(TransformStream)\"| T1\n  T1 -->|\"per-event map()<br/>SSE chunk → ResponseStreamEvent[]\"| T2\n  T2 -->|\"accumulate StreamState<br/>intercept terminal event<br/>buildResponseObject()<br/>save session\"| T3\n  T3 -->|\"serialize to SSE wire format<br/>event: xxx\\ndata: {...}\\n\\n\"| BYTES\n\n  style upstream fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n  style godex fill:#0f3460,stroke:#16213e,color:#e0e0e0\n  style client fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n```\n\n### Transformer Roles\n\n| Stage | Transformer | Input | Output | Side Effects |\n|-------|------------|-------|--------|-------------|\n| 1 | `ProviderEventToResponseTransformer` | `JsonServerSentEvent<TChunk>` | `ResponseStreamEvent` | Calls `StreamMapper.map()` per event |\n| 2 | `ResponseSessionPersistenceTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Accumulates `StreamState`, on terminal event calls `buildResponseObject()` + saves session (skipped when `store=false`) |\n| 3 | `ResponseSseEncodeTransformer` | `ResponseStreamEvent` | `Uint8Array` (SSE wire format) | Serializes to `event:` / `data:` lines |\n\n## Error Hierarchy\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class GodeXError {\n    +name: string\n    +code: string\n    +status: number\n    +context: object\n    +toLogEntry() object\n  }\n\n  class ServerError {\n    +status: 400-499\n    +context: object\n  }\n\n  class AdapterError {\n    +status: 400-499\n    +context: unsupported parameters / tools / input items\n  }\n\n  class ProviderError {\n    +status: 502\n    +context: upstream status / body / headers\n  }\n\n  class SessionError {\n    +status: 400-409\n    +context: chain metadata\n  }\n\n  GodeXError <|-- ServerError\n  GodeXError <|-- AdapterError\n  GodeXError <|-- ProviderError\n  GodeXError <|-- SessionError\n\n  note for GodeXError \"Base error with structured logging support.<br/>All errors carry domain codes (e.g. server.request.invalid_json).\"\n  note for ProviderError \"Wraps upstream HTTP failures:<br/>rate limits, timeouts, 5xx.\"\n  note for SessionError \"Chain resolution failures:<br/>not found, cycles, depth exceeded.\"\n```\n\n## Project Structure\n\n```\nsrc/\n├── cli/              Commander CLI (serve, config check, init)\n├── config/           godex.yaml schema, env interpolation, defaults\n├── context/          ApplicationContext (DI container), ResponsesContext (per-request)\n├── adapter/          Adapter interface, DefaultAdapter, stream transformers\n│   ├── mapper/       RequestMapper / ResponseMapper / StreamMapper contracts\n│   └── transformers/ ProviderEvent → Response → SSE encode pipeline\n├── providers/        Provider registry + builtin factories\n│   └── zhipu/        Reference provider: mapper, chat-client, tools, messages\n├── resolver/         ModelResolver (model selector → provider + model)\n├── server/           Bun HTTP server, Router, routes (/v1/responses, /health, /v1/models)\n├── session/          ResponseSessionStore (Memory + SQLite), chain resolution\n├── error/            GodeXError hierarchy with domain codes\n├── protocol/openai/  OpenAI-compatible type definitions\n├── logger/           Structured JSON logger\n└── e2e/              End-to-end tests with mocked upstream\n```\n\n## Quick Start\n\n```bash\n# Install dependencies\nbun install\n\n# Build standalone binary (current platform)\nbun run build\n\n# Create config interactively\nbun run start -- init\n\n# Start server (default port 5678)\nbun run dev\n\n# Or run the compiled binary directly\n./platforms/darwin-arm64/bin/godex serve\n```\n\n### godex.yaml\n\n```yaml\nserver:\n  port: 5678\n\ndefault_provider: zhipu\n\nproviders:\n  zhipu:\n    api_key: ${ZHIPU_API_KEY}\n    base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    models:\n      \"gpt-4o\": glm-4.7         # model name mapping\n      \"*\": glm-5.1              # catch-all fallback\n\nsession:\n  backend: sqlite               # or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info                   # trace | debug | info | warn | error\n```\n\n### Adding a Provider\n\nImplement these interfaces in `src/providers/<name>/`:\n\n| Interface | Purpose |\n|-----------|---------|\n| `Provider<TReq, TRes, TChunk>` | Bundles mapper + chatClient + capabilities |\n| `ProviderMapper<TReq, TRes, TChunk>` | request / response / stream mapping functions |\n| `ChatClient<TReq, TRes, TChunk>` | `chat()` and `streamChat()` HTTP calls |\n\nRegister the factory in `src/providers/builtin.ts`:\n\n```ts\nregistrar.registerFactory(\"myprovider\", (config) =>\n  createMyProvider(config) as Provider<unknown, unknown, unknown>\n);\n```\n\n## Usage\n\n```bash\n# Install — no Bun required at runtime\nnpm install -g @ahoo-wang/godex\n\n# Create config interactively\ngodex init\n\n# Start the gateway\ngodex serve\n```\n\nGodeX ships as a **standalone native binary** with zero runtime dependencies. npm's `postinstall` automatically selects the correct binary for your platform. The only prerequisite is Node.js >= 18 (needed only during `npm install`).\n\nGodeX exposes an **OpenAI-compatible Responses API** at `http://localhost:5678` (port is configurable). Point any tool that speaks the OpenAI protocol at this endpoint:\n\n### With Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=http://localhost:5678/v1\nexport OPENAI_API_KEY=any-value          # not validated by GodeX, must be set\ncodex\n```\n\n### With OpenAI SDK\n\n```ts\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n  baseURL: \"http://localhost:5678/v1\",\n  apiKey: \"any-value\",      // passed through, not validated\n});\n\nconst response = await client.responses.create({\n  model: \"gpt-4o\",          // mapped to glm-4.7 via godex.yaml models table\n  input: \"Hello!\",\n});\n```\n\n### Model selection\n\n```\nmodel: \"gpt-4o\"              → resolved via default_provider model mapping\nmodel: \"zhipu/glm-4.7\"       → explicit provider/model selector\nmodel: \"openai/gpt-4o\"       → routes to configured openai provider\n```\n\nThe `models` map in `godex.yaml` lets you translate standard model names into provider-native ones — no code changes needed in the client.\n\n### Health check\n\n```bash\ncurl http://localhost:5678/health\n# {\"status\":\"ok\",\"providers\":[\"zhipu\"],\"unsupported_providers\":[]}\n```\n\n## Publishing\n\nThe main `@ahoo-wang/godex` npm package is a lightweight shell. Native binaries are shipped as platform-specific optional dependencies:\n\n```\n@ahoo-wang/godex (wrapper package, 0 runtime deps)\n├── engines: { node: \">=18.0.0\" }    ← only for postinstall\n├── postinstall: scripts/install.cjs   ← detects platform, links binary\n└── optionalDependencies:\n    ├── @ahoo-wang/godex-darwin-arm64           ← macOS Apple Silicon\n    ├── @ahoo-wang/godex-darwin-x64             ← macOS Intel\n    ├── @ahoo-wang/godex-linux-x64              ← Linux x86_64\n    ├── @ahoo-wang/godex-linux-arm64            ← Linux ARM64\n    ├── @ahoo-wang/godex-win32-x64              ← Windows x86_64\n    └── @ahoo-wang/godex-win32-arm64            ← Windows ARM64\n\n# Publishing flow:\n# 1. Make the GitHub repository public, configure NPM_TOKEN, then push the release commit.\n# 2. Create a GitHub Release tagged vX.Y.Z.\n# 3. The Release workflow builds all platform binaries.\n# 4. The Release workflow uploads binary archives and SHA256SUMS to Release Assets.\n# 5. The Release workflow publishes platform packages first, then @ahoo-wang/godex.\n```\n\n## Commands\n\n```bash\nbun run dev          # Hot-reload dev server on port 13145\nbun run build        # Compile native binary for current platform\nbun run compile:all  # Cross-compile all 6 platforms locally\nbun run test         # Unit + integration tests\nbun run test:e2e     # E2E with mocked upstream\nbun run typecheck    # tsc --noEmit\nbun run lint         # Biome check\nbun run ci           # Full CI pipeline\n```\n"}, "4efdae266f9afddefd1bb315f1ce0ca0eec2bc37": {"t": 1785748595.9668593, "n": 14008, "h": "68bfa99d01237efe", "c": "# Godex\n\nOpenAI Responses API gateway — translates `/v1/responses` into upstream Chat Completions API calls, so **any LLM provider can drive Codex**.\n\n[![codecov](https://codecov.io/gh/Ahoo-Wang/Godex/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/Godex)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n## Architecture\n\n```mermaid\nC4Context\n  title Godex — System Context\n\n  Person(user, \"Developer / Codex CLI\", \"Sends Responses API requests<br/>via the OpenAI-compatible endpoint\")\n  System(godex_svr, \"Godex Server\", \"Translates Responses API → Chat Completions API<br/>Bun HTTP server on configurable port\")\n  SystemDb(sessions, \"Session Store\", \"Stores response history for<br/>previous_response_id chain resolution<br/>SQLite (persistent) or In-Memory\")\n  System_Ext(zhipu, \"Zhipu (智谱)\", \"Chat Completions API provider\")\n  System_Ext(openai, \"OpenAI\", \"Chat Completions API provider\")\n  System_Ext(other, \"Custom Provider\", \"Any Chat Completions<br/>compatible backend\")\n\n  Rel(user, godex_svr, \"POST /v1/responses, GET /v1/models, GET /health\", \"HTTP/SSE\")\n  Rel(godex_svr, sessions, \"save / resolve chains\")\n  Rel(godex_svr, zhipu, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, openai, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, other, \"POST /chat/completions\", \"HTTPS\")\n```\n\n## Request Flow\n\n```mermaid\nsequenceDiagram\n  actor C as Client (Codex CLI)\n  participant R as Router\n  participant AC as ApplicationContext\n  participant RC as ResponsesContext\n  participant MR as ModelResolver\n  participant SS as SessionStore\n  participant REG as Registrar\n  participant A as Adapter (DefaultAdapter)\n  participant PM as ProviderMapper\n  participant CC as ChatClient\n  participant UP as Upstream API\n\n  C->>R: POST /v1/responses\n  R->>RC: ResponsesContext.create(app, body)\n\n  activate RC\n    RC->>MR: resolve(model)\n    MR-->>RC: { provider, model }\n    RC->>RC: validate provider config\n\n    opt previous_response_id\n      RC->>SS: resolveChain(id)\n      SS-->>RC: session snapshot\n    end\n\n    RC->>REG: resolve(provider)\n    REG-->>RC: Provider instance\n  deactivate RC\n\n  alt stream = true\n    R->>A: adapter.stream(ctx)\n    activate A\n      A->>PM: request.map(ctx)\n      PM-->>A: upstream request\n      A->>CC: streamChat(req)\n      CC->>UP: POST (SSE)\n      UP-->>CC: SSE chunks\n      CC-->>A: ReadableStream<SSE>\n      A->>A: pipeTransform → ProviderEventToResponseTransformer\n      A->>A: pipeTransform → ResponseSessionPersistenceTransformer\n      A-->>R: ReadableStream<ResponseStreamEvent>\n    deactivate A\n    R->>R: pipeTransform → ResponseSseEncodeTransformer\n    R-->>C: SSE byte stream\n  else stream = false\n    R->>A: adapter.request(ctx)\n    activate A\n      A->>PM: request.map(ctx)\n      PM-->>A: upstream request\n      A->>CC: chat(req)\n      CC->>UP: POST\n      UP-->>CC: JSON response\n      CC-->>A: upstream response\n      A->>PM: response.map(ctx, res)\n      PM-->>A: ResponseObject\n      A->>SS: save(session)\n      A-->>R: ResponseObject\n    deactivate A\n    R-->>C: JSON response\n  end\n```\n\n## Component Model\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class ApplicationContext {\n    +config: GodexConfig\n    +logger: Logger\n    +resolver: ModelResolver\n    +registrar: Registrar\n    +adapter: Adapter\n    +sessionStore: ResponseSessionStore\n  }\n\n  class ResponsesContext {\n    +app: ApplicationContext\n    +request: ResponseCreateRequest\n    +session: ResponseSessionSnapshot\n    +resolved: ResolvedModel\n    +provider: Provider\n    +responseId: string\n    +requestId: string\n    +logger: Logger\n    +create(app, body)$ Promise~ResponsesContext~\n  }\n\n  class ModelResolver {\n    -defaultProvider: string\n    -providerConfigs: Record\n    +resolve(model) ResolvedModel\n  }\n\n  class Registrar {\n    -factories: Map~string, ProviderFactory~\n    +registerFactory(name, factory)\n    +build(providers)\n    +resolve(name) Provider\n    +list() string[]\n  }\n\n  class Adapter {\n    <<interface>>\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class DefaultAdapter {\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class Provider {\n    <<interface>>\n    +name: string\n    +mapper: ProviderMapper\n    +chatClient: ChatClient\n    +capabilities: ProviderCapabilities\n  }\n\n  class ProviderMapper {\n    <<interface>>\n    +request: RequestMapper\n    +response: ResponseMapper\n    +stream: StreamMapper\n  }\n\n  class ChatClient {\n    <<interface>>\n    +chat(req) Promise~TRes~\n    +streamChat(req) Promise~ReadableStream~\n  }\n\n  class RequestMapper {\n    <<interface>>\n    +map(ctx) TReq\n  }\n\n  class ResponseMapper {\n    <<interface>>\n    +map(ctx, result) ResponseObject\n  }\n\n  class StreamMapper {\n    <<interface>>\n    +map(ctx, event) ResponseStreamEvent[]\n    +buildResponseObject(ctx, state) ResponseObject\n  }\n\n  class ResponseSessionStore {\n    <<interface>>\n    +get(id) StoredResponseSession\n    +save(session, opts)\n    +resolveChain(id, opts) ResponseSessionSnapshot\n    +delete(id)\n    +close()\n  }\n\n  class Router {\n    -routes: Route[]\n    +register(route)\n    +dispatch(req) Promise~Response~\n  }\n\n  ApplicationContext --> ResponsesContext : creates\n  ApplicationContext --> ModelResolver\n  ApplicationContext --> Registrar\n  ApplicationContext --> Adapter\n  ApplicationContext --> ResponseSessionStore\n  ResponsesContext --> Provider : uses\n  Provider --> ProviderMapper\n  Provider --> ChatClient\n  ProviderMapper --> RequestMapper\n  ProviderMapper --> ResponseMapper\n  ProviderMapper --> StreamMapper\n  Adapter <|.. DefaultAdapter\n  DefaultAdapter --> ProviderMapper : calls\n  DefaultAdapter --> ChatClient : calls\n  DefaultAdapter --> ResponseSessionStore : saves\n  Router --> ResponsesContext : dispatches to\n```\n\n## Stream Pipeline\n\n```mermaid\nflowchart LR\n  subgraph upstream[\"Upstream Provider\"]\n    SSE[\"SSE Chunks<br/>(JsonServerSentEvent)\"]\n  end\n\n  subgraph godex[\"Godex Stream Pipeline\"]\n    T1[\"ProviderEventTo<br/>ResponseTransformer\"]\n    T2[\"ResponseSession<br/>PersistenceTransformer\"]\n    T3[\"ResponseSse<br/>EncodeTransformer\"]\n  end\n\n  subgraph client[\"Client\"]\n    BYTES[\"SSE Bytes<br/>(text/event-stream)\"]\n  end\n\n  SSE -->|\"pipeThrough(TransformStream)\"| T1\n  T1 -->|\"per-event map()<br/>SSE chunk → ResponseStreamEvent[]\"| T2\n  T2 -->|\"accumulate StreamState<br/>intercept terminal event<br/>buildResponseObject()<br/>save session\"| T3\n  T3 -->|\"serialize to SSE wire format<br/>event: xxx\\ndata: {...}\\n\\n\"| BYTES\n\n  style upstream fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n  style godex fill:#0f3460,stroke:#16213e,color:#e0e0e0\n  style client fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n```\n\n### Transformer Roles\n\n| Stage | Transformer | Input | Output | Side Effects |\n|-------|------------|-------|--------|-------------|\n| 1 | `ProviderEventToResponseTransformer` | `JsonServerSentEvent<TChunk>` | `ResponseStreamEvent` | Calls `StreamMapper.map()` per event |\n| 2 | `ResponseSessionPersistenceTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Accumulates `StreamState`, on terminal event calls `buildResponseObject()` + saves session (skipped when `store=false`) |\n| 3 | `ResponseSseEncodeTransformer` | `ResponseStreamEvent` | `Uint8Array` (SSE wire format) | Serializes to `event:` / `data:` lines |\n\n## Error Hierarchy\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class GodexError {\n    +name: string\n    +code: string\n    +status: number\n    +context: object\n    +toLogEntry() object\n  }\n\n  class ServerError {\n    +status: 400-499\n    +context: object\n  }\n\n  class AdapterError {\n    +status: 400-499\n    +context: unsupported parameters / tools / input items\n  }\n\n  class ProviderError {\n    +status: 502\n    +context: upstream status / body / headers\n  }\n\n  class SessionError {\n    +status: 400-409\n    +context: chain metadata\n  }\n\n  GodexError <|-- ServerError\n  GodexError <|-- AdapterError\n  GodexError <|-- ProviderError\n  GodexError <|-- SessionError\n\n  note for GodexError \"Base error with structured logging support.<br/>All errors carry domain codes (e.g. server.request.invalid_json).\"\n  note for ProviderError \"Wraps upstream HTTP failures:<br/>rate limits, timeouts, 5xx.\"\n  note for SessionError \"Chain resolution failures:<br/>not found, cycles, depth exceeded.\"\n```\n\n## Project Structure\n\n```\nsrc/\n├── cli/              Commander CLI (serve, config check, init)\n├── config/           godex.yaml schema, env interpolation, defaults\n├── context/          ApplicationContext (DI container), ResponsesContext (per-request)\n├── adapter/          Adapter interface, DefaultAdapter, stream transformers\n│   ├── mapper/       RequestMapper / ResponseMapper / StreamMapper contracts\n│   └── transformers/ ProviderEvent → Response → SSE encode pipeline\n├── providers/        Provider registry + builtin factories\n│   └── zhipu/        Reference provider: mapper, chat-client, tools, messages\n├── resolver/         ModelResolver (model selector → provider + model)\n├── server/           Bun HTTP server, Router, routes (/v1/responses, /health, /v1/models)\n├── session/          ResponseSessionStore (Memory + SQLite), chain resolution\n├── error/            GodexError hierarchy with domain codes\n├── protocol/openai/  OpenAI-compatible type definitions\n├── logger/           Structured JSON logger\n└── e2e/              End-to-end tests with mocked upstream\n```\n\n## Quick Start\n\n```bash\n# Install dependencies\nbun install\n\n# Build standalone binary (current platform)\nbun run build\n\n# Create config interactively\nbun run start -- init\n\n# Start server (default port 5678)\nbun run dev\n\n# Or run the compiled binary directly\n./platforms/darwin-arm64/bin/godex serve\n```\n\n### godex.yaml\n\n```yaml\nserver:\n  port: 5678\n\ndefault_provider: zhipu\n\nproviders:\n  zhipu:\n    api_key: ${ZHIPU_API_KEY}\n    base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    models:\n      \"gpt-4o\": glm-4.7         # model name mapping\n      \"*\": glm-5.1              # catch-all fallback\n\nsession:\n  backend: sqlite               # or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info                   # trace | debug | info | warn | error\n```\n\n### Adding a Provider\n\nImplement these interfaces in `src/providers/<name>/`:\n\n| Interface | Purpose |\n|-----------|---------|\n| `Provider<TReq, TRes, TChunk>` | Bundles mapper + chatClient + capabilities |\n| `ProviderMapper<TReq, TRes, TChunk>` | request / response / stream mapping functions |\n| `ChatClient<TReq, TRes, TChunk>` | `chat()` and `streamChat()` HTTP calls |\n\nRegister the factory in `src/providers/builtin.ts`:\n\n```ts\nregistrar.registerFactory(\"myprovider\", (config) =>\n  createMyProvider(config) as Provider<unknown, unknown, unknown>\n);\n```\n\n## Usage\n\n```bash\n# Install — no Bun required at runtime\nnpm install -g @ahoo-wang/godex\n\n# Create config interactively\ngodex init\n\n# Start the gateway\ngodex serve\n```\n\nGodex ships as a **standalone native binary** with zero runtime dependencies. npm's `postinstall` automatically selects the correct binary for your platform. The only prerequisite is Node.js >= 18 (needed only during `npm install`).\n\nGodex exposes an **OpenAI-compatible Responses API** at `http://localhost:5678` (port is configurable). Point any tool that speaks the OpenAI protocol at this endpoint:\n\n### With Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=http://localhost:5678/v1\nexport OPENAI_API_KEY=any-value          # not validated by Godex, must be set\ncodex\n```\n\n### With OpenAI SDK\n\n```ts\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n  baseURL: \"http://localhost:5678/v1\",\n  apiKey: \"any-value\",      // passed through, not validated\n});\n\nconst response = await client.responses.create({\n  model: \"gpt-4o\",          // mapped to glm-4.7 via godex.yaml models table\n  input: \"Hello!\",\n});\n```\n\n### Model selection\n\n```\nmodel: \"gpt-4o\"              → resolved via default_provider model mapping\nmodel: \"zhipu/glm-4.7\"       → explicit provider/model selector\nmodel: \"openai/gpt-4o\"       → routes to configured openai provider\n```\n\nThe `models` map in `godex.yaml` lets you translate standard model names into provider-native ones — no code changes needed in the client.\n\n### Health check\n\n```bash\ncurl http://localhost:5678/health\n# {\"status\":\"ok\",\"providers\":[\"zhipu\"],\"unsupported_providers\":[]}\n```\n\n## Publishing\n\nThe main `@ahoo-wang/godex` npm package is a lightweight shell. Native binaries are shipped as platform-specific optional dependencies:\n\n```\n@ahoo-wang/godex (wrapper package, 0 runtime deps)\n├── engines: { node: \">=18.0.0\" }    ← only for postinstall\n├── postinstall: scripts/install.cjs   ← detects platform, links binary\n└── optionalDependencies:\n    ├── @ahoo-wang/godex-darwin-arm64           ← macOS Apple Silicon\n    ├── @ahoo-wang/godex-darwin-x64             ← macOS Intel\n    ├── @ahoo-wang/godex-linux-x64              ← Linux x86_64\n    ├── @ahoo-wang/godex-linux-arm64            ← Linux ARM64\n    ├── @ahoo-wang/godex-win32-x64              ← Windows x86_64\n    └── @ahoo-wang/godex-win32-arm64            ← Windows ARM64\n\n# Publishing flow:\n# 1. Make the GitHub repository public, configure NPM_TOKEN, then push the release commit.\n# 2. Create a GitHub Release tagged vX.Y.Z.\n# 3. The Release workflow builds all platform binaries.\n# 4. The Release workflow uploads binary archives and SHA256SUMS to Release Assets.\n# 5. The Release workflow publishes platform packages first, then @ahoo-wang/godex.\n```\n\n## Commands\n\n```bash\nbun run dev          # Hot-reload dev server on port 13145\nbun run build        # Compile native binary for current platform\nbun run compile:all  # Cross-compile all 6 platforms locally\nbun run test         # Unit + integration tests\nbun run test:e2e     # E2E with mocked upstream\nbun run typecheck    # tsc --noEmit\nbun run lint         # Biome check\nbun run ci           # Full CI pipeline\n```\n"}, "c5fd6efd9acc242e7d855f8cc3bcdb2cd0c34ac3": {"t": 1785748600.2031837, "n": 14001, "h": "f439ea7839c6a250", "c": "# Godex\n\nOpenAI Responses API gateway — translates `/v1/responses` into upstream Chat Completions API calls, so **any LLM provider can drive Codex**.\n\n[![codecov](https://codecov.io/gh/Ahoo-Wang/Godex/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/Godex)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n## Architecture\n\n```mermaid\nC4Context\n  title Godex — System Context\n\n  Person(user, \"Developer / Codex CLI\", \"Sends Responses API requests<br/>via the OpenAI-compatible endpoint\")\n  System(godex_svr, \"Godex Server\", \"Translates Responses API → Chat Completions API<br/>Bun HTTP server on configurable port\")\n  SystemDb(sessions, \"Session Store\", \"Stores response history for<br/>previous_response_id chain resolution<br/>SQLite (persistent) or In-Memory\")\n  System_Ext(zhipu, \"Zhipu (智谱)\", \"Chat Completions API provider\")\n  System_Ext(openai, \"OpenAI\", \"Chat Completions API provider\")\n  System_Ext(other, \"Custom Provider\", \"Any Chat Completions<br/>compatible backend\")\n\n  Rel(user, godex_svr, \"POST /v1/responses, GET /v1/models, GET /health\", \"HTTP/SSE\")\n  Rel(godex_svr, sessions, \"save / resolve chains\")\n  Rel(godex_svr, zhipu, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, openai, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, other, \"POST /chat/completions\", \"HTTPS\")\n```\n\n## Request Flow\n\n```mermaid\nsequenceDiagram\n  actor C as Client (Codex CLI)\n  participant R as Router\n  participant AC as ApplicationContext\n  participant RC as ResponsesContext\n  participant MR as ModelResolver\n  participant SS as SessionStore\n  participant REG as Registrar\n  participant A as Adapter (DefaultAdapter)\n  participant PM as ProviderMapper\n  participant CC as ChatClient\n  participant UP as Upstream API\n\n  C->>R: POST /v1/responses\n  R->>RC: ResponsesContext.create(app, body)\n\n  activate RC\n    RC->>MR: resolve(model)\n    MR-->>RC: { provider, model }\n    RC->>RC: validate provider config\n\n    opt previous_response_id\n      RC->>SS: resolveChain(id)\n      SS-->>RC: session snapshot\n    end\n\n    RC->>REG: resolve(provider)\n    REG-->>RC: Provider instance\n  deactivate RC\n\n  alt stream = true\n    R->>A: adapter.stream(ctx)\n    activate A\n      A->>PM: request.map(ctx)\n      PM-->>A: upstream request\n      A->>CC: streamChat(req)\n      CC->>UP: POST (SSE)\n      UP-->>CC: SSE chunks\n      CC-->>A: ReadableStream<SSE>\n      A->>A: pipeTransform → ProviderEventToResponseTransformer\n      A->>A: pipeTransform → ResponseSessionPersistenceTransformer\n      A-->>R: ReadableStream<ResponseStreamEvent>\n    deactivate A\n    R->>R: pipeTransform → ResponseSseEncodeTransformer\n    R-->>C: SSE byte stream\n  else stream = false\n    R->>A: adapter.request(ctx)\n    activate A\n      A->>PM: request.map(ctx)\n      PM-->>A: upstream request\n      A->>CC: chat(req)\n      CC->>UP: POST\n      UP-->>CC: JSON response\n      CC-->>A: upstream response\n      A->>PM: response.map(ctx, res)\n      PM-->>A: ResponseObject\n      A->>SS: save(session)\n      A-->>R: ResponseObject\n    deactivate A\n    R-->>C: JSON response\n  end\n```\n\n## Component Model\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class ApplicationContext {\n    +config: GodexConfig\n    +logger: Logger\n    +resolver: ModelResolver\n    +registrar: Registrar\n    +adapter: Adapter\n    +sessionStore: ResponseSessionStore\n  }\n\n  class ResponsesContext {\n    +app: ApplicationContext\n    +request: ResponseCreateRequest\n    +session: ResponseSessionSnapshot\n    +resolved: ResolvedModel\n    +provider: Provider\n    +responseId: string\n    +requestId: string\n    +logger: Logger\n    +create(app, body)$ Promise~ResponsesContext~\n  }\n\n  class ModelResolver {\n    -defaultProvider: string\n    -providerConfigs: Record\n    +resolve(model) ResolvedModel\n  }\n\n  class Registrar {\n    -factories: Map~string, ProviderFactory~\n    +registerFactory(name, factory)\n    +build(providers)\n    +resolve(name) Provider\n    +list() string[]\n  }\n\n  class Adapter {\n    <<interface>>\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class DefaultAdapter {\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class Provider {\n    <<interface>>\n    +name: string\n    +mapper: ProviderMapper\n    +chatClient: ChatClient\n    +capabilities: ProviderCapabilities\n  }\n\n  class ProviderMapper {\n    <<interface>>\n    +request: RequestMapper\n    +response: ResponseMapper\n    +stream: StreamMapper\n  }\n\n  class ChatClient {\n    <<interface>>\n    +chat(req) Promise~TRes~\n    +streamChat(req) Promise~ReadableStream~\n  }\n\n  class RequestMapper {\n    <<interface>>\n    +map(ctx) TReq\n  }\n\n  class ResponseMapper {\n    <<interface>>\n    +map(ctx, result) ResponseObject\n  }\n\n  class StreamMapper {\n    <<interface>>\n    +map(ctx, event) ResponseStreamEvent[]\n    +buildResponseObject(ctx, state) ResponseObject\n  }\n\n  class ResponseSessionStore {\n    <<interface>>\n    +get(id) StoredResponseSession\n    +save(session, opts)\n    +resolveChain(id, opts) ResponseSessionSnapshot\n    +delete(id)\n    +close()\n  }\n\n  class Router {\n    -routes: Route[]\n    +register(route)\n    +dispatch(req) Promise~Response~\n  }\n\n  ApplicationContext --> ResponsesContext : creates\n  ApplicationContext --> ModelResolver\n  ApplicationContext --> Registrar\n  ApplicationContext --> Adapter\n  ApplicationContext --> ResponseSessionStore\n  ResponsesContext --> Provider : uses\n  Provider --> ProviderMapper\n  Provider --> ChatClient\n  ProviderMapper --> RequestMapper\n  ProviderMapper --> ResponseMapper\n  ProviderMapper --> StreamMapper\n  Adapter <|.. DefaultAdapter\n  DefaultAdapter --> ProviderMapper : calls\n  DefaultAdapter --> ChatClient : calls\n  DefaultAdapter --> ResponseSessionStore : saves\n  Router --> ResponsesContext : dispatches to\n```\n\n## Stream Pipeline\n\n```mermaid\nflowchart LR\n  subgraph upstream[\"Upstream Provider\"]\n    SSE[\"SSE Chunks<br/>(JsonServerSentEvent)\"]\n  end\n\n  subgraph godex[\"Godex Stream Pipeline\"]\n    T1[\"ProviderEventTo<br/>ResponseTransformer\"]\n    T2[\"ResponseSession<br/>PersistenceTransformer\"]\n    T3[\"ResponseSse<br/>EncodeTransformer\"]\n  end\n\n  subgraph client[\"Client\"]\n    BYTES[\"SSE Bytes<br/>(text/event-stream)\"]\n  end\n\n  SSE -->|\"pipeThrough(TransformStream)\"| T1\n  T1 -->|\"per-event map()<br/>SSE chunk → ResponseStreamEvent[]\"| T2\n  T2 -->|\"accumulate StreamState<br/>intercept terminal event<br/>buildResponseObject()<br/>save session\"| T3\n  T3 -->|\"serialize to SSE wire format<br/>event: xxx\\ndata: {...}\\n\\n\"| BYTES\n\n  style upstream fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n  style godex fill:#0f3460,stroke:#16213e,color:#e0e0e0\n  style client fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n```\n\n### Transformer Roles\n\n| Stage | Transformer | Input | Output | Side Effects |\n|-------|------------|-------|--------|-------------|\n| 1 | `ProviderEventToResponseTransformer` | `JsonServerSentEvent<TChunk>` | `ResponseStreamEvent` | Calls `StreamMapper.map()` per event |\n| 2 | `ResponseSessionPersistenceTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Accumulates `StreamState`, on terminal event calls `buildResponseObject()` + saves session (skipped when `store=false`) |\n| 3 | `ResponseSseEncodeTransformer` | `ResponseStreamEvent` | `Uint8Array` (SSE wire format) | Serializes to `event:` / `data:` lines |\n\n## Error Hierarchy\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class GodexError {\n    +name: string\n    +code: string\n    +status: number\n    +context: object\n    +toLogEntry() object\n  }\n\n  class ServerError {\n    +status: 400-499\n    +context: object\n  }\n\n  class AdapterError {\n    +status: 400-499\n    +context: unsupported parameters / tools / input items\n  }\n\n  class ProviderError {\n    +status: 502\n    +context: upstream status / body / headers\n  }\n\n  class SessionError {\n    +status: 400-409\n    +context: chain metadata\n  }\n\n  GodexError <|-- ServerError\n  GodexError <|-- AdapterError\n  GodexError <|-- ProviderError\n  GodexError <|-- SessionError\n\n  note for GodexError \"Base error with structured logging support.<br/>All errors carry domain codes (e.g. server.request.invalid_json).\"\n  note for ProviderError \"Wraps upstream HTTP failures:<br/>rate limits, timeouts, 5xx.\"\n  note for SessionError \"Chain resolution failures:<br/>not found, cycles, depth exceeded.\"\n```\n\n## Project Structure\n\n```\nsrc/\n├── cli/              Commander CLI (serve, config check, init)\n├── config/           godex.yaml schema, env interpolation, defaults\n├── context/          ApplicationContext (DI container), ResponsesContext (per-request)\n├── adapter/          Adapter interface, DefaultAdapter, stream transformers\n│   ├── mapper/       RequestMapper / ResponseMapper / StreamMapper contracts\n│   └── transformers/ ProviderEvent → Response → SSE encode pipeline\n├── providers/        Provider registry + builtin factories\n│   └── zhipu/        Reference provider: mapper, chat-client, tools, messages\n├── resolver/         ModelResolver (model selector → provider + model)\n├── server/           Bun HTTP server, Router, routes (/v1/responses, /health, /v1/models)\n├── session/          ResponseSessionStore (Memory + SQLite), chain resolution\n├── error/            GodexError hierarchy with domain codes\n├── protocol/openai/  OpenAI-compatible type definitions\n├── logger/           Structured JSON logger\n└── e2e/              End-to-end tests with mocked upstream\n```\n\n## Quick Start\n\n```bash\n# Install dependencies\nbun install\n\n# Build standalone binary (current platform)\nbun run build\n\n# Create config interactively\nbun run start -- init\n\n# Start server (default port 5678)\nbun run dev\n\n# Or run the compiled binary directly\n./platforms/darwin-arm64/bin/godex serve\n```\n\n### godex.yaml\n\n```yaml\nserver:\n  port: 5678\n\ndefault_provider: zhipu\n\nproviders:\n  zhipu:\n    api_key: ${ZHIPU_API_KEY}\n    base_url: https://open.bigmodel.cn/api/paas/v4\n    models:\n      \"gpt-4o\": glm-4.7         # model name mapping\n      \"*\": glm-5.1              # catch-all fallback\n\nsession:\n  backend: sqlite               # or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info                   # trace | debug | info | warn | error\n```\n\n### Adding a Provider\n\nImplement these interfaces in `src/providers/<name>/`:\n\n| Interface | Purpose |\n|-----------|---------|\n| `Provider<TReq, TRes, TChunk>` | Bundles mapper + chatClient + capabilities |\n| `ProviderMapper<TReq, TRes, TChunk>` | request / response / stream mapping functions |\n| `ChatClient<TReq, TRes, TChunk>` | `chat()` and `streamChat()` HTTP calls |\n\nRegister the factory in `src/providers/builtin.ts`:\n\n```ts\nregistrar.registerFactory(\"myprovider\", (config) =>\n  createMyProvider(config) as Provider<unknown, unknown, unknown>\n);\n```\n\n## Usage\n\n```bash\n# Install — no Bun required at runtime\nnpm install -g @ahoo-wang/godex\n\n# Create config interactively\ngodex init\n\n# Start the gateway\ngodex serve\n```\n\nGodex ships as a **standalone native binary** with zero runtime dependencies. npm's `postinstall` automatically selects the correct binary for your platform. The only prerequisite is Node.js >= 18 (needed only during `npm install`).\n\nGodex exposes an **OpenAI-compatible Responses API** at `http://localhost:5678` (port is configurable). Point any tool that speaks the OpenAI protocol at this endpoint:\n\n### With Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=http://localhost:5678/v1\nexport OPENAI_API_KEY=any-value          # not validated by Godex, must be set\ncodex\n```\n\n### With OpenAI SDK\n\n```ts\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n  baseURL: \"http://localhost:5678/v1\",\n  apiKey: \"any-value\",      // passed through, not validated\n});\n\nconst response = await client.responses.create({\n  model: \"gpt-4o\",          // mapped to glm-4.7 via godex.yaml models table\n  input: \"Hello!\",\n});\n```\n\n### Model selection\n\n```\nmodel: \"gpt-4o\"              → resolved via default_provider model mapping\nmodel: \"zhipu/glm-4.7\"       → explicit provider/model selector\nmodel: \"openai/gpt-4o\"       → routes to configured openai provider\n```\n\nThe `models` map in `godex.yaml` lets you translate standard model names into provider-native ones — no code changes needed in the client.\n\n### Health check\n\n```bash\ncurl http://localhost:5678/health\n# {\"status\":\"ok\",\"providers\":[\"zhipu\"],\"unsupported_providers\":[]}\n```\n\n## Publishing\n\nThe main `@ahoo-wang/godex` npm package is a lightweight shell. Native binaries are shipped as platform-specific optional dependencies:\n\n```\n@ahoo-wang/godex (wrapper package, 0 runtime deps)\n├── engines: { node: \">=18.0.0\" }    ← only for postinstall\n├── postinstall: scripts/install.cjs   ← detects platform, links binary\n└── optionalDependencies:\n    ├── @ahoo-wang/godex-darwin-arm64           ← macOS Apple Silicon\n    ├── @ahoo-wang/godex-darwin-x64             ← macOS Intel\n    ├── @ahoo-wang/godex-linux-x64              ← Linux x86_64\n    ├── @ahoo-wang/godex-linux-arm64            ← Linux ARM64\n    ├── @ahoo-wang/godex-win32-x64              ← Windows x86_64\n    └── @ahoo-wang/godex-win32-arm64            ← Windows ARM64\n\n# Publishing flow:\n# 1. Make the GitHub repository public, configure NPM_TOKEN, then push the release commit.\n# 2. Create a GitHub Release tagged vX.Y.Z.\n# 3. The Release workflow builds all platform binaries.\n# 4. The Release workflow uploads binary archives and SHA256SUMS to Release Assets.\n# 5. The Release workflow publishes platform packages first, then @ahoo-wang/godex.\n```\n\n## Commands\n\n```bash\nbun run dev          # Hot-reload dev server on port 13145\nbun run build        # Compile native binary for current platform\nbun run compile:all  # Cross-compile all 6 platforms locally\nbun run test         # Unit + integration tests\nbun run test:e2e     # E2E with mocked upstream\nbun run typecheck    # tsc --noEmit\nbun run lint         # Biome check\nbun run ci           # Full CI pipeline\n```\n"}, "9810874f9f6a26da6104ad12014ad184dec39781": {"t": 1785748601.3320577, "n": 13877, "h": "81173767ff437d51", "c": "# Godex\n\nOpenAI Responses API gateway — translates `/v1/responses` into upstream Chat Completions API calls, so **any LLM provider can drive Codex**.\n\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n## Architecture\n\n```mermaid\nC4Context\n  title Godex — System Context\n\n  Person(user, \"Developer / Codex CLI\", \"Sends Responses API requests<br/>via the OpenAI-compatible endpoint\")\n  System(godex_svr, \"Godex Server\", \"Translates Responses API → Chat Completions API<br/>Bun HTTP server on configurable port\")\n  SystemDb(sessions, \"Session Store\", \"Stores response history for<br/>previous_response_id chain resolution<br/>SQLite (persistent) or In-Memory\")\n  System_Ext(zhipu, \"Zhipu (智谱)\", \"Chat Completions API provider\")\n  System_Ext(openai, \"OpenAI\", \"Chat Completions API provider\")\n  System_Ext(other, \"Custom Provider\", \"Any Chat Completions<br/>compatible backend\")\n\n  Rel(user, godex_svr, \"POST /v1/responses, GET /v1/models, GET /health\", \"HTTP/SSE\")\n  Rel(godex_svr, sessions, \"save / resolve chains\")\n  Rel(godex_svr, zhipu, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, openai, \"POST /chat/completions\", \"HTTPS\")\n  Rel(godex_svr, other, \"POST /chat/completions\", \"HTTPS\")\n```\n\n## Request Flow\n\n```mermaid\nsequenceDiagram\n  actor C as Client (Codex CLI)\n  participant R as Router\n  participant AC as ApplicationContext\n  participant RC as ResponsesContext\n  participant MR as ModelResolver\n  participant SS as SessionStore\n  participant REG as Registrar\n  participant A as Adapter (DefaultAdapter)\n  participant PM as ProviderMapper\n  participant CC as ChatClient\n  participant UP as Upstream API\n\n  C->>R: POST /v1/responses\n  R->>RC: ResponsesContext.create(app, body)\n\n  activate RC\n    RC->>MR: resolve(model)\n    MR-->>RC: { provider, model }\n    RC->>RC: validate provider config\n\n    opt previous_response_id\n      RC->>SS: resolveChain(id)\n      SS-->>RC: session snapshot\n    end\n\n    RC->>REG: resolve(provider)\n    REG-->>RC: Provider instance\n  deactivate RC\n\n  alt stream = true\n    R->>A: adapter.stream(ctx)\n    activate A\n      A->>PM: request.map(ctx)\n      PM-->>A: upstream request\n      A->>CC: streamChat(req)\n      CC->>UP: POST (SSE)\n      UP-->>CC: SSE chunks\n      CC-->>A: ReadableStream<SSE>\n      A->>A: pipeTransform → ProviderEventToResponseTransformer\n      A->>A: pipeTransform → ResponseSessionPersistenceTransformer\n      A-->>R: ReadableStream<ResponseStreamEvent>\n    deactivate A\n    R->>R: pipeTransform → ResponseSseEncodeTransformer\n    R-->>C: SSE byte stream\n  else stream = false\n    R->>A: adapter.request(ctx)\n    activate A\n      A->>PM: request.map(ctx)\n      PM-->>A: upstream request\n      A->>CC: chat(req)\n      CC->>UP: POST\n      UP-->>CC: JSON response\n      CC-->>A: upstream response\n      A->>PM: response.map(ctx, res)\n      PM-->>A: ResponseObject\n      A->>SS: save(session)\n      A-->>R: ResponseObject\n    deactivate A\n    R-->>C: JSON response\n  end\n```\n\n## Component Model\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class ApplicationContext {\n    +config: GodexConfig\n    +logger: Logger\n    +resolver: ModelResolver\n    +registrar: Registrar\n    +adapter: Adapter\n    +sessionStore: ResponseSessionStore\n  }\n\n  class ResponsesContext {\n    +app: ApplicationContext\n    +request: ResponseCreateRequest\n    +session: ResponseSessionSnapshot\n    +resolved: ResolvedModel\n    +provider: Provider\n    +responseId: string\n    +requestId: string\n    +logger: Logger\n    +create(app, body)$ Promise~ResponsesContext~\n  }\n\n  class ModelResolver {\n    -defaultProvider: string\n    -providerConfigs: Record\n    +resolve(model) ResolvedModel\n  }\n\n  class Registrar {\n    -factories: Map~string, ProviderFactory~\n    +registerFactory(name, factory)\n    +build(providers)\n    +resolve(name) Provider\n    +list() string[]\n  }\n\n  class Adapter {\n    <<interface>>\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class DefaultAdapter {\n    +request(ctx) Promise~ResponseObject~\n    +stream(ctx) Promise~ReadableStream~\n  }\n\n  class Provider {\n    <<interface>>\n    +name: string\n    +mapper: ProviderMapper\n    +chatClient: ChatClient\n    +capabilities: ProviderCapabilities\n  }\n\n  class ProviderMapper {\n    <<interface>>\n    +request: RequestMapper\n    +response: ResponseMapper\n    +stream: StreamMapper\n  }\n\n  class ChatClient {\n    <<interface>>\n    +chat(req) Promise~TRes~\n    +streamChat(req) Promise~ReadableStream~\n  }\n\n  class RequestMapper {\n    <<interface>>\n    +map(ctx) TReq\n  }\n\n  class ResponseMapper {\n    <<interface>>\n    +map(ctx, result) ResponseObject\n  }\n\n  class StreamMapper {\n    <<interface>>\n    +map(ctx, event) ResponseStreamEvent[]\n    +buildResponseObject(ctx, state) ResponseObject\n  }\n\n  class ResponseSessionStore {\n    <<interface>>\n    +get(id) StoredResponseSession\n    +save(session, opts)\n    +resolveChain(id, opts) ResponseSessionSnapshot\n    +delete(id)\n    +close()\n  }\n\n  class Router {\n    -routes: Route[]\n    +register(route)\n    +dispatch(req) Promise~Response~\n  }\n\n  ApplicationContext --> ResponsesContext : creates\n  ApplicationContext --> ModelResolver\n  ApplicationContext --> Registrar\n  ApplicationContext --> Adapter\n  ApplicationContext --> ResponseSessionStore\n  ResponsesContext --> Provider : uses\n  Provider --> ProviderMapper\n  Provider --> ChatClient\n  ProviderMapper --> RequestMapper\n  ProviderMapper --> ResponseMapper\n  ProviderMapper --> StreamMapper\n  Adapter <|.. DefaultAdapter\n  DefaultAdapter --> ProviderMapper : calls\n  DefaultAdapter --> ChatClient : calls\n  DefaultAdapter --> ResponseSessionStore : saves\n  Router --> ResponsesContext : dispatches to\n```\n\n## Stream Pipeline\n\n```mermaid\nflowchart LR\n  subgraph upstream[\"Upstream Provider\"]\n    SSE[\"SSE Chunks<br/>(JsonServerSentEvent)\"]\n  end\n\n  subgraph godex[\"Godex Stream Pipeline\"]\n    T1[\"ProviderEventTo<br/>ResponseTransformer\"]\n    T2[\"ResponseSession<br/>PersistenceTransformer\"]\n    T3[\"ResponseSse<br/>EncodeTransformer\"]\n  end\n\n  subgraph client[\"Client\"]\n    BYTES[\"SSE Bytes<br/>(text/event-stream)\"]\n  end\n\n  SSE -->|\"pipeThrough(TransformStream)\"| T1\n  T1 -->|\"per-event map()<br/>SSE chunk → ResponseStreamEvent[]\"| T2\n  T2 -->|\"accumulate StreamState<br/>intercept terminal event<br/>buildResponseObject()<br/>save session\"| T3\n  T3 -->|\"serialize to SSE wire format<br/>event: xxx\\ndata: {...}\\n\\n\"| BYTES\n\n  style upstream fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n  style godex fill:#0f3460,stroke:#16213e,color:#e0e0e0\n  style client fill:#1a1a2e,stroke:#16213e,color:#e0e0e0\n```\n\n### Transformer Roles\n\n| Stage | Transformer | Input | Output | Side Effects |\n|-------|------------|-------|--------|-------------|\n| 1 | `ProviderEventToResponseTransformer` | `JsonServerSentEvent<TChunk>` | `ResponseStreamEvent` | Calls `StreamMapper.map()` per event |\n| 2 | `ResponseSessionPersistenceTransformer` | `ResponseStreamEvent` | `ResponseStreamEvent` | Accumulates `StreamState`, on terminal event calls `buildResponseObject()` + saves session (skipped when `store=false`) |\n| 3 | `ResponseSseEncodeTransformer` | `ResponseStreamEvent` | `Uint8Array` (SSE wire format) | Serializes to `event:` / `data:` lines |\n\n## Error Hierarchy\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class GodexError {\n    +name: string\n    +code: string\n    +status: number\n    +context: object\n    +toLogEntry() object\n  }\n\n  class ServerError {\n    +status: 400-499\n    +context: object\n  }\n\n  class AdapterError {\n    +status: 400-499\n    +context: unsupported parameters / tools / input items\n  }\n\n  class ProviderError {\n    +status: 502\n    +context: upstream status / body / headers\n  }\n\n  class SessionError {\n    +status: 400-409\n    +context: chain metadata\n  }\n\n  GodexError <|-- ServerError\n  GodexError <|-- AdapterError\n  GodexError <|-- ProviderError\n  GodexError <|-- SessionError\n\n  note for GodexError \"Base error with structured logging support.<br/>All errors carry domain codes (e.g. server.request.invalid_json).\"\n  note for ProviderError \"Wraps upstream HTTP failures:<br/>rate limits, timeouts, 5xx.\"\n  note for SessionError \"Chain resolution failures:<br/>not found, cycles, depth exceeded.\"\n```\n\n## Project Structure\n\n```\nsrc/\n├── cli/              Commander CLI (serve, config check, init)\n├── config/           godex.yaml schema, env interpolation, defaults\n├── context/          ApplicationContext (DI container), ResponsesContext (per-request)\n├── adapter/          Adapter interface, DefaultAdapter, stream transformers\n│   ├── mapper/       RequestMapper / ResponseMapper / StreamMapper contracts\n│   └── transformers/ ProviderEvent → Response → SSE encode pipeline\n├── providers/        Provider registry + builtin factories\n│   └── zhipu/        Reference provider: mapper, chat-client, tools, messages\n├── resolver/         ModelResolver (model selector → provider + model)\n├── server/           Bun HTTP server, Router, routes (/v1/responses, /health, /v1/models)\n├── session/          ResponseSessionStore (Memory + SQLite), chain resolution\n├── error/            GodexError hierarchy with domain codes\n├── protocol/openai/  OpenAI-compatible type definitions\n├── logger/           Structured JSON logger\n└── e2e/              End-to-end tests with mocked upstream\n```\n\n## Quick Start\n\n```bash\n# Install dependencies\nbun install\n\n# Build standalone binary (current platform)\nbun run build\n\n# Create config interactively\nbun run start -- init\n\n# Start server (default port 5678)\nbun run dev\n\n# Or run the compiled binary directly\n./platforms/darwin-arm64/bin/godex serve\n```\n\n### godex.yaml\n\n```yaml\nserver:\n  port: 5678\n\ndefault_provider: zhipu\n\nproviders:\n  zhipu:\n    api_key: ${ZHIPU_API_KEY}\n    base_url: https://open.bigmodel.cn/api/paas/v4\n    models:\n      \"gpt-4o\": glm-4.7         # model name mapping\n      \"*\": glm-5.1              # catch-all fallback\n\nsession:\n  backend: sqlite               # or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info                   # trace | debug | info | warn | error\n```\n\n### Adding a Provider\n\nImplement these interfaces in `src/providers/<name>/`:\n\n| Interface | Purpose |\n|-----------|---------|\n| `Provider<TReq, TRes, TChunk>` | Bundles mapper + chatClient + capabilities |\n| `ProviderMapper<TReq, TRes, TChunk>` | request / response / stream mapping functions |\n| `ChatClient<TReq, TRes, TChunk>` | `chat()` and `streamChat()` HTTP calls |\n\nRegister the factory in `src/providers/builtin.ts`:\n\n```ts\nregistrar.registerFactory(\"myprovider\", (config) =>\n  createMyProvider(config) as Provider<unknown, unknown, unknown>\n);\n```\n\n## Usage\n\n```bash\n# Install — no Bun required at runtime\nnpm install -g @ahoo-wang/godex\n\n# Create config interactively\ngodex init\n\n# Start the gateway\ngodex serve\n```\n\nGodex ships as a **standalone native binary** with zero runtime dependencies. npm's `postinstall` automatically selects the correct binary for your platform. The only prerequisite is Node.js >= 18 (needed only during `npm install`).\n\nGodex exposes an **OpenAI-compatible Responses API** at `http://localhost:5678` (port is configurable). Point any tool that speaks the OpenAI protocol at this endpoint:\n\n### With Codex CLI\n\n```bash\nexport OPENAI_BASE_URL=http://localhost:5678/v1\nexport OPENAI_API_KEY=any-value          # not validated by Godex, must be set\ncodex\n```\n\n### With OpenAI SDK\n\n```ts\nimport OpenAI from \"openai\";\n\nconst client = new OpenAI({\n  baseURL: \"http://localhost:5678/v1\",\n  apiKey: \"any-value\",      // passed through, not validated\n});\n\nconst response = await client.responses.create({\n  model: \"gpt-4o\",          // mapped to glm-4.7 via godex.yaml models table\n  input: \"Hello!\",\n});\n```\n\n### Model selection\n\n```\nmodel: \"gpt-4o\"              → resolved via default_provider model mapping\nmodel: \"zhipu/glm-4.7\"       → explicit provider/model selector\nmodel: \"openai/gpt-4o\"       → routes to configured openai provider\n```\n\nThe `models` map in `godex.yaml` lets you translate standard model names into provider-native ones — no code changes needed in the client.\n\n### Health check\n\n```bash\ncurl http://localhost:5678/health\n# {\"status\":\"ok\",\"providers\":[\"zhipu\"],\"unsupported_providers\":[]}\n```\n\n## Publishing\n\nThe main `@ahoo-wang/godex` npm package is a lightweight shell. Native binaries are shipped as platform-specific optional dependencies:\n\n```\n@ahoo-wang/godex (wrapper package, 0 runtime deps)\n├── engines: { node: \">=18.0.0\" }    ← only for postinstall\n├── postinstall: scripts/install.cjs   ← detects platform, links binary\n└── optionalDependencies:\n    ├── @ahoo-wang/godex-darwin-arm64           ← macOS Apple Silicon\n    ├── @ahoo-wang/godex-darwin-x64             ← macOS Intel\n    ├── @ahoo-wang/godex-linux-x64              ← Linux x86_64\n    ├── @ahoo-wang/godex-linux-arm64            ← Linux ARM64\n    ├── @ahoo-wang/godex-win32-x64              ← Windows x86_64\n    └── @ahoo-wang/godex-win32-arm64            ← Windows ARM64\n\n# Publishing flow:\n# 1. Make the GitHub repository public, configure NPM_TOKEN, then push the release commit.\n# 2. Create a GitHub Release tagged vX.Y.Z.\n# 3. The Release workflow builds all platform binaries.\n# 4. The Release workflow uploads binary archives and SHA256SUMS to Release Assets.\n# 5. The Release workflow publishes platform packages first, then @ahoo-wang/godex.\n```\n\n## Commands\n\n```bash\nbun run dev          # Hot-reload dev server on port 13145\nbun run build        # Compile native binary for current platform\nbun run compile:all  # Cross-compile all 6 platforms locally\nbun run test         # Unit + integration tests\nbun run test:e2e     # E2E with mocked upstream\nbun run typecheck    # tsc --noEmit\nbun run lint         # Biome check\nbun run ci           # Full CI pipeline\n```\n"}, "e4b02fa899c22db59bd7a257edccad7d2aae168d": {"t": 1786068485.0977347, "n": 12669, "h": "26353555bff64e0a", "c": "<div align=\"center\">\n\n<img src=\"design/assets/01-logo-system/png/godex-logo-horizontal-transparent-800x233.png\" alt=\"GodeX\" width=\"480\" />\n\n**Make every model a Codex engine.**\n\nOpenAI-compatible Responses API gateway for Codex, CLI tools and developer agents.\n\n[![npm version](https://img.shields.io/npm/v/@ahoo-wang/godex?logo=npm)](https://www.npmjs.com/package/@ahoo-wang/godex)\n[![codecov](https://codecov.io/gh/Ahoo-Wang/GodeX/graph/badge.svg?token=dJQrmUAiXu)](https://codecov.io/gh/Ahoo-Wang/GodeX)\n[![Bun](https://img.shields.io/badge/runtime-bun-f9f1e0?logo=bun)](https://bun.sh)\n[![TypeScript](https://img.shields.io/badge/lang-typescript-3178c6?logo=typescript)](https://www.typescriptlang.org/)\n\n[**English Documentation**](https://godex.ahoo.me/) · [**中文文档**](https://godex.ahoo.me/zh/)\n</div>\n\nGodeX lets clients that speak the OpenAI Responses API use providers such as DeepSeek, Xiaomi, MiniMax, and Zhipu through one local server.\n\n\n\n## Highlights\n\n- OpenAI-compatible `POST /v1/responses` endpoint with sync and streaming responses.\n- `GET /v1/models` aliases so clients can use stable model names while GodeX routes to provider/model targets.\n- Built-in bridge providers for DeepSeek, Xiaomi, MiniMax, and Zhipu.\n- Provider capability planning for request parameters, tools, `tool_choice`, structured output formats, reasoning, and stream usage.\n- Hybrid web search support with provider-native declarations for Zhipu/Xiaomi and GodeX-managed hosted search through the Zhipu Web Search API.\n- Responses `previous_response_id` session chains backed by memory or SQLite.\n- Trace recording for provider requests, provider responses, stream events, usage, and errors.\n- Native Bun runtime, TypeScript source, and compiled platform binaries for releases.\n\n## Built-in Providers\n\n| Provider | Reasoning | GodeX Input | Tool Choice | Response Format | Cached Tokens | Default Model |\n|----------|-----------|-------------|-------------|-----------------|---------------|---------------|\n| DeepSeek | native | text | auto, none, required, function | text, json_object | ✅ | `deepseek-v4-pro` |\n| Xiaomi   | boolean | text | auto | text, json_object | ✅ | `mimo-v2.5-pro` |\n| MiniMax  | boolean | text, image, video | auto, none, required, function | text, json_object | ✅ | `MiniMax-M3` |\n| Zhipu    | boolean | text | auto, none | text, json_object | ✅ | `glm-5.2` |\n\n## Architecture\n\n![GodeX architecture](docs/assets/godex-architecture-branded.png)\n\n## Component Interaction\n\n![GodeX component interaction](docs/assets/godex-component-interaction-branded.png)\n\n## Install\n\nFor local development:\n\n```bash\ngit clone https://github.com/Ahoo-Wang/GodeX.git\ncd GodeX\nbun install\n```\n\nFor package use, install the published package and run the `godex` binary:\n\n```bash\nnpm install -g @ahoo-wang/godex\ngodex --help\n```\n\n### Docker\n\nPre-built images are published to Docker Hub and GitHub Container Registry:\n\n```bash\ndocker pull ahoowang/godex:latest\n# or\ndocker pull ghcr.io/ahoo-wang/godex:latest\n```\n\nRun with a config file:\n\n```bash\ndocker run -d \\\n  --name godex \\\n  -p 5678:5678 \\\n  -e ZHIPU_API_KEY=your-key \\\n  -e DEEPSEEK_API_KEY=your-key \\\n  -e MINIMAX_API_KEY=your-key \\\n  -e MIMO_API_KEY=your-key \\\n  -v ./godex.yaml:/etc/godex/godex.yaml:ro \\\n  -v godex-data:/data \\\n  ahoowang/godex:latest\n```\n\nThe image supports `linux/amd64` and `linux/arm64`.\n\n- Config file: `/etc/godex/godex.yaml`\n- Data directory (sessions, trace): `/data`\n- Default port: `5678`\n\n## Quick Start\n\nCreate a config and start the server:\n\n```bash\ngodex init\ngodex serve --config ./godex.yaml\n```\n\nThe interactive wizard walks you through selecting providers, entering base URLs and API keys, and writes the config file automatically.\n\nAlternatively, create `godex.yaml` manually:\n\n```yaml\nserver:\n  port: 5678\n  host: 0.0.0.0\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    #\n    # 这些 alias 是 GodeX routing policy，不代表与 OpenAI 原模型能力等价。\n    # 依据优先级：公开 benchmark > 官方模型定位 > Provider 产品说明。\n    # -------------------------------------------------------------------------\n\n    # Codex 默认主力：复杂编码 / computer use / research workflows\n    # 依据：DeepSeek V4-Pro 在 SWE / Terminal / Codeforces / GDPval-AA 上公开成绩强。\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n\n    # Codex 旗舰：coding + reasoning + tool use + agentic workflows\n    # 依据：DeepSeek V4-Pro 有更完整的公开 coding/agentic benchmark 覆盖。\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n\n    # Codex mini：subagents\n    gpt-5.4-mini: \"zhipu/glm-5.1\"\n\n    # Codex 编码专用：复杂软件工程\n    # 依据：DeepSeek V4-Pro 的 SWE Verified / SWE Pro / Terminal Bench 表现。\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n\n    # Codex spark：近实时编码迭代\n    gpt-5.3-codex-spark: \"zhipu/glm-5.1\"\n\n    # 上一代通用 coding / agentic fallback\n    # 严谨起见仍走 DeepSeek；不强行映射到 Zhipu。\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # -------------------------------------------------------------------------\n    # Provider native models\n    # -------------------------------------------------------------------------\n\n    deepseek-v4-pro: \"deepseek/deepseek-v4-pro\"\n    deepseek-v4-flash: \"deepseek/deepseek-v4-flash\"\n\n    mimo-v2.5-pro: \"xiaomi/mimo-v2.5-pro\"\n    mimo-v2.5: \"xiaomi/mimo-v2.5\"\n\n    glm-5.1: \"zhipu/glm-5.1\"\n    glm-5-turbo: \"zhipu/glm-5-turbo\"\n    glm-4.7: \"zhipu/glm-4.7\"\n    glm-4.5-air: \"zhipu/glm-4.5-air\"\n\n    MiniMax-M3: \"minimax/MiniMax-M3\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n  zhipu:\n    spec: zhipu\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n  minimax:\n    spec: minimax\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n  xiaomi:\n    spec: xiaomi\n    credentials:\n      api_key: ${MIMO_API_KEY}\n    endpoint:\n      base_url: https://api.xiaomimimo.com/v1\n\nweb_search:\n  enabled: true\n  mode: auto\n  provider: zhipu\n  on_unavailable: client_tool_call\n  max_iterations: 2\n\nsession:\n  backend: sqlite\n\nlogging:\n  level: info\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  capture_payload: false\n```\n\nStart the server:\n\n```bash\ngodex serve --config ./godex.yaml\n```\n\nThe dev command starts GodeX on port `13145`; the default runtime config port is `5678`.\n\n## API\n\n### Health\n\n```bash\ncurl http://localhost:5678/health\n```\n\n### Models\n\n```bash\ncurl http://localhost:5678/v1/models\n```\n\n`/v1/models` lists configured aliases, excluding the wildcard alias `*`.\n\n### Responses\n\n```bash\ncurl http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"input\": \"Write a short TypeScript function that adds two numbers.\"\n  }'\n```\n\nStreaming uses standard Responses SSE event names:\n\n```bash\ncurl -N http://localhost:5678/v1/responses \\\n  -H 'content-type: application/json' \\\n  -d '{\n    \"model\": \"gpt-5.5\",\n    \"stream\": true,\n    \"input\": \"Explain Bun streams in two sentences.\"\n  }'\n```\n\n## Model Routing\n\nClients may pass either:\n\n- A provider-qualified selector such as `deepseek/deepseek-v4-pro`\n- A configured alias such as `gpt-5.5`\n- A bare model name, which resolves through `default_provider` when no alias matches\n\nAliases must map to `provider/model` values, and the provider must exist in `providers`.\n\n\n## Codex Integration\n\nConnect the Codex desktop app to GodeX by adding a custom provider in `~/.codex/config.toml`:\n\n```toml\nmodel = \"gpt-5.5\"\nmodel_provider = \"godex\"\n\n[model_providers.godex]\nname = \"GodeX\"\nbase_url = \"http://127.0.0.1:5678/v1\"\nwire_api = \"responses\"\nrequires_openai_auth = false\nsupports_websockets = false\n```\n\nModel aliases (`gpt-5.5`, `gpt-5.4`, `gpt-5.4-mini`, etc.) are resolved by GodeX using the `models.aliases` map in `godex.yaml` — Codex itself only needs the alias name.\n\n\n## Provider Bridge Behavior\n\nGodeX builds a provider request in three steps:\n\n1. Resolve the client model selector to a configured provider and upstream model.\n2. Plan compatibility from the provider `ProviderSpec`, including request parameters, tool declarations, `tool_choice`, response format, reasoning, and stream usage.\n3. Convert Responses input and session history into Chat Completions messages, call the upstream provider, and reconstruct a Responses object or Responses SSE stream.\n\nProvider-specific differences belong in each provider's `spec.ts`, `hooks.ts`, protocol types, and HTTP client. Shared Responses-to-Chat policy belongs under `src/bridge`.\n\n## Structured Output\n\nWhen a provider supports `json_object` but not native `json_schema`, GodeX can degrade strict `json_schema` requests to `json_object`.\n\nFor strict downgraded schemas:\n\n- The schema instruction is added to the provider prompt preamble for the current request.\n- The provider receives `response_format: { \"type\": \"json_object\" }`.\n- GodeX validates that the final output is valid JSON.\n- Invalid sync output fails the response; invalid stream output is rewritten to a terminal `response.failed` event.\n\nThe validator checks JSON syntax, not full JSON Schema conformance.\n\n## Sessions\n\nResponses can be stored and replayed with `previous_response_id`.\n\n- `session.backend: memory` keeps history in process memory.\n- `session.backend: sqlite` persists history to SQLite.\n- Requests with `store: false` are not saved.\n- The session chain stores request snapshots and response output items, then rebuilds provider-neutral history on the next turn.\n\n## Trace Database\n\nTracing is enabled by default and writes SQLite rows to `./data/trace.db` unless configured otherwise.\n\nTrace records include:\n\n- Provider request metadata and final patched request payload summaries\n- Provider request lifecycle events without duplicating full request bodies\n- Sync provider response bodies as summarized payloads\n- Raw and transformed stream events\n- Usage details, including cached tokens when provided by the upstream\n- Route and provider errors\n\nSet `trace.capture_payload: true` to persist payload JSON up to `trace.payload_max_bytes` for trace rows that carry payloads. Keep it disabled for sensitive environments.\n\n## Development\n\n```bash\nbun install                  # Install dependencies\nbun run dev                  # Dev server with hot reload on port 13145\nbun run start                # Start server from source\nbun run build                # Build a binary for the current platform\nbun run compile:all          # Cross-compile all supported platform packages\n```\n\nQuality gates:\n\n```bash\nbun run typecheck            # TypeScript\nbun run lint                 # Biome check\nbun run lint:fix             # Biome autofix\nbun run format               # Biome format\nbun run test                 # Unit and integration tests, excluding src/e2e\nbun run test:e2e             # Mocked end-to-end tests\nbun run test:zhipu           # Live Zhipu tests; requires ZHIPU_API_KEY\nbun run test:deepseek        # Live DeepSeek tests; requires DEEPSEEK_API_KEY\nbun run test:minimax         # Live MiniMax tests; requires MINIMAX_API_KEY\nbun run test:xiaomi         # Live Xiaomi tests; requires MIMO_API_KEY\nbun run check                # typecheck + lint + test\nbun run ci                   # typecheck + biome ci + test + e2e\n```\n\n## Source Map\n\n```text\nsrc/\n  cli/          Commander CLI, init wizard, runtime config loading\n  config/       godex.yaml schema, defaults, env interpolation\n  context/      ApplicationContext and per-request ResponsesContext\n  bridge/       Provider-agnostic Responses-to-Chat planning and reconstruction\n  providers/    Built-in provider specs, hooks, clients, and registry\n  responses/    Sync and stream request pipelines\n  server/       Bun routes for /health, /v1/models, /v1/responses\n  session/      Memory and SQLite response session stores\n  trace/        SQLite trace recorder and usage/error/event mappers\n  protocol/     OpenAI protocol type definitions\n  error/        GodeXError hierarchy and domain codes\n```\n\n## Provider Development\n\nProvider folders follow this shape:\n\n```text\nsrc/providers/<name>/\n  spec.ts       ProviderSpec declaration\n  client.ts     ProviderEdge construction with ChatProviderClient\n  hooks.ts      Provider-specific patching, accessors, usage, stream deltas\n  protocol/     Provider DTOs when needed\n  index.ts      Public exports\n```\n\nAdd shared compatibility policy to `src/bridge`; add shared provider transport or protocol helpers to `src/providers/shared`.\n\n## License\n\nApache-2.0. See [LICENSE](./LICENSE).\n"}}, "wiki/zh/onboarding/executive-guide.md": {"9efb5d28b803166fc52e46da8d469512befd054b": {"t": 1785595263.5417087, "n": 13316, "h": "f28c1bfcdb2e21ba", "c": "---\ntitle: \"高管指南\"\ndescription: \"面向 VP/总监级工程领导者的战略概览 -- 能力、风险、成本模型和投资逻辑。\"\nkeywords: \"GodeX, 高管指南, 战略, 风险评估, 成本模型, 架构\"\n---\n\n# 高管指南\n\n> **受众**：评估 GodeX 用于组织采纳、成本优化或战略 AI 基础设施决策的 VP/总监级工程领导者。\n>\n> **阅读时间**：约 15 分钟。\n>\n> **无代码片段** -- 本指南仅使用服务级图表和表格。\n\n---\n\n## GodeX 是什么\n\nGodeX 是一个兼容 OpenAI 的 Responses API 网关。它位于 AI 编程代理（Codex CLI、Claude Code、Cursor）和非 OpenAI LLM 提供商（DeepSeek、Xiaomi、Zhipu/ChatGLM、MiniMax）之间，在两种协议之间透明地转换请求和响应。\n\n代理以 OpenAI 的 Responses API 格式发出请求。GodeX 将这些请求转换为每个提供商的 Chat Completions API 格式，调用上游提供商，再将响应转换回来。代理完全感知不到它并非在与 OpenAI 对话。\n\n这之所以重要，是因为 Responses API 正在成为下一代 AI 编程工具的标准协议。没有 GodeX，每个非 OpenAI 提供商都需要针对每个代理进行定制集成工作。有了 GodeX，一个网关就能处理所有提供商。\n\n---\n\n## 能力矩阵\n\n### 核心服务能力\n\n| 能力 | 描述 | 商业价值 |\n|-----------|-------------|----------------|\n| **协议转换** | 将 OpenAI Responses API 请求转换为提供商特定的 Chat Completions API 调用，并反向转换 | 客户端零代码改动 |\n| **多提供商路由** | 通过单一配置文件支持 DeepSeek、Xiaomi、Zhipu/ChatGLM 和 MiniMax | 供应商多元化而无需碎片化 |\n| **流式支持** | 实时透传服务器发送事件（SSE） | 代理获得与 OpenAI 无异的流式响应 |\n| **会话管理** | 通过 `previous_response_id` 链式解析实现多轮对话 | 代理在多轮之间保持对话上下文 |\n| **模型别名** | 将友好的模型名称（如 `gpt-5.5`）映射到实际的提供商/模型组合 | 团队切换提供商无需更改代理配置 |\n| **工具调用** | 将 Codex 工具声明（shell、apply_patch、function）转换为提供商等价物 | 代理在非 OpenAI 提供商上执行工具 |\n| **结构化输出** | 当提供商不支持时，将 JSON Schema 降级为 JSON Object | 跨提供商一致的输出格式保证 |\n| **请求追踪** | 基于 SQLite 的请求、用量、事件和错误的追踪记录 | 完整的审计追踪和调试能力 |\n| **用量追踪** | 跟踪每个请求的输入令牌、输出令牌、缓存令牌和推理令牌 | 成本可见性和费用分摊能力 |\n| **Docker 部署** | 预构建的 linux/amd64 和 linux/arm64 镜像 | 标准化容器部署 |\n\n### 能力成熟度\n\n| 能力 | 成熟度 | 备注 |\n|-----------|----------|-------|\n| 协议转换（同步） | 稳定 | 核心路径，经过充分测试 |\n| 协议转换（流式） | 稳定 | 基于状态机的 SSE 重建 |\n| 工具调用降级 | 稳定 | 内置 Codex 工具映射到所有提供商的 `function` |\n| JSON Schema 结构化输出 | Beta | 降级为 `json_object` 并带校验 |\n| 推理/思维令牌 | Beta | DeepSeek：原生支持。Xiaomi：布尔开关。Zhipu：布尔开关。MiniMax：布尔 adaptive/disabled thinking |\n| 缓存令牌追踪 | 稳定 | 当提供商返回缓存元数据时报告 |\n| 会话链式解析 | 稳定 | 循环检测、深度限制、未完成响应处理 |\n| 网页搜索 | 稳定 | 提供商原生透传（智谱、小米）和通过智谱 Web Search API 的 GodeX 托管搜索 |\n| 多租户隔离 | 未建设 | 目前为单租户 |\n| 自动提供商故障转移 | 未建设 | 目标提供商宕机时请求失败 |\n\n---\n\n## 技术投资逻辑\n\n### 为什么存在这个项目\n\nAI 编程代理正在向 OpenAI Responses API 收敛为标准协议。但最好和最便宜的模型并不总是来自 OpenAI。团队面临选择：锁定 OpenAI，或者为每个替代提供商构建和维护定制集成。\n\nGodeX 消除了这种权衡。一个网关，一个配置文件，任意支持的提供商。\n\n### 商业价值驱动因素\n\n| 驱动因素 | 说明 |\n|--------|-------------|\n| **成本优化** | DeepSeek 和 MiniMax 模型比 GPT-4 级别模型便宜得多。GodeX 让团队使用这些更便宜的提供商，无需重写代理代码或维护提供商特定的 SDK 集成。 |\n| **供应商多元化** | 依赖单一 LLM 提供商是战略风险。GodeX 让路由到多个提供商变得轻而易举，减少锁定并提供谈判筹码。 |\n| **中国市场接入** | Xiaomi、Zhipu（ChatGLM）和 MiniMax 是领先的中国市场 LLM 提供商。GodeX 使在中国部署 AI 编程工具的团队能够使用国内提供商而无需定制集成工作。Zhipu 编程端点已预配置。 |\n| **协议面向未来** | Responses API 是 OpenAI 面向代理式 AI 交互的较新标准。随着更多工具采纳它，GodeX 使组织能够使用任何 Chat Completions 提供商，无需等待原生的 Responses API 支持。 |\n| **运维简单性** | 单个二进制文件或 Docker 容器。无外部数据库。无消息队列。SQLite 用于会话和追踪。一个 YAML 配置文件。 |\n\n### 战略定位\n\n```mermaid\ngraph LR\n  subgraph agents[\"代理层\"]\n    CODEX[\"Codex CLI\"]\n    CLAUDE[\"Claude Code\"]\n    CURSOR[\"Cursor\"]\n  end\n\n  subgraph Gateway Layer\n    GODEX[\"GodeX<br>协议转换<br>会话管理<br>请求追踪\"]\n  end\n\n  subgraph providers[\"提供商层\"]\n    DEEPSEEK[\"DeepSeek<br>高性价比编程\"]\n    XIAOMI[\"Xiaomi / MiMo<br>推理与中国市场\"]\n    ZHIPU[\"Zhipu / ChatGLM<br>中国市场\"]\n    MINIMAX[\"MiniMax<br>快速响应\"]\n    FUTURE[\"未来提供商<br>可扩展规约模式\"]\n  end\n\n  CODEX -->|\"Responses API\"| GODEX\n  CLAUDE -->|\"Responses API\"| GODEX\n  CURSOR -->|\"Responses API\"| GODEX\n  GODEX -->|\"Chat Completions API\"| DEEPSEEK\n  GODEX -->|\"Chat Completions API\"| XIAOMI\n  GODEX -->|\"Chat Completions API\"| ZHIPU\n  GODEX -->|\"Chat Completions API\"| MINIMAX\n  GODEX -->|\"Chat Completions API\"| FUTURE\n\n  style GODEX fill:#161b22,stroke:#6d5dfc,color:#e6edf3\n  style CODEX fill:#2d333b,stroke:#6d5dfc,color:#e6edf3\n  style CLAUDE fill:#2d333b,stroke:#6d5dfc,color:#e6edf3\n  style CURSOR fill:#2d333b,stroke:#6d5dfc,color:#e6edf3\n  style DEEPSEEK fill:#2d333b,stroke:#6d5dfc,color:#e6edf3\n  style XIAOMI fill:#2d333b,stroke:#6d5dfc,color:#e6edf3\n  style ZHIPU fill:#2d333b,stroke:#6d5dfc,color:#e6edf3\n  style MINIMAX fill:#2d333b,stroke:#6d5dfc,color:#e6edf3\n  style FUTURE fill:#2d333b,stroke:#30363d,color:#e6edf3\n```\n\nGodeX 占据代理工具和模型提供商之间的转换层。添加新提供商只需实现一个规约接口 -- 无需更改代理，无需更改桥接内核。\n\n---\n\n## 架构概览\n\n### 服务图\n\n下图展示了从 AI 编程代理经 GodeX 到上游提供商再返回的请求流程。\n\n```mermaid\nsequenceDiagram\n  autonumber\n  participant Agent as AI 编程代理\n  participant GodeX as GodeX 网关\n  participant Resolver as 模型解析器\n  participant Session as 会话存储\n  participant Bridge as 桥接内核\n  participant Provider as 上游提供商\n\n  Agent->>GodeX: POST /v1/responses（OpenAI 格式）\n  GodeX->>Resolver: 解析模型名称为 provider/model\n  Resolver-->>GodeX: 提供商 + 上游模型 ID\n\n  alt 多轮对话\n    GodeX->>Session: 查找 previous_response_id 链\n    Session-->>GodeX: 对话历史\n  end\n\n  GodeX->>Bridge: 转换为 Chat Completions 格式\n  Bridge->>Bridge: 兼容性规划（工具、输出格式、推理）\n  Bridge-->>GodeX: 提供商就绪的请求\n\n  GodeX->>Provider: POST /chat/completions\n  Provider-->>GodeX: 响应（JSON 或 SSE 流）\n  GodeX->>Bridge: 重建 Responses API 格式\n  Bridge-->>GodeX: OpenAI Responses 对象\n\n  GodeX->>Session: 持久化响应（如果 store=true）\n  GodeX->>GodeX: 记录追踪（请求、用量、事件）\n\n  GodeX-->>Agent: ResponseObject JSON 或 SSE 流\n```\n\n### 组件职责\n\n| 组件 | 职责 |\n|-----------|---------------|\n| **服务器路由** | 接受 `/v1/responses`、`/v1/models` 和 `/health` HTTP 请求 |\n| **模型解析器** | 将模型名称和别名转换为提供商/模型对 |\n| **会话存储** | 持久化和检索多轮对话链 |\n| **桥接内核** | 在 Responses API 和 Chat Completions API 之间转换；规划兼容性；处理工具映射、输出契约和流式状态 |\n| **提供商规约** | 声明每个提供商的能力、端点配置和协议特性 |\n| **追踪记录器** | 将请求元数据、用量、事件和错误记录到 SQLite |\n| **错误层级** | 面向服务器、桥接、提供商和会话失败的领域特定错误码 |\n\n### 提供商规约模式\n\n每个提供商由一个精简的规约定义，声明其能力而非实现。桥接内核读取这些声明并自动规划兼容性。\n\n```mermaid\ngraph TB\n  subgraph ProviderSpec[\"提供商规约\"]\n    CAPS[\"能力<br>参数、工具、格式、推理\"]\n    ENDPOINT[\"端点<br>基础 URL、认证方案\"]\n    HOOKS[\"钩子<br>请求修补、用量映射、流增量\"]\n    ACCESSORS[\"访问器<br>响应文本、结束原因、用量\"]\n  end\n\n  subgraph BridgeKernel[\"桥接内核\"]\n    COMPAT[\"兼容性规划器\"]\n    TOOLS[\"工具规划器\"]\n    OUTPUT[\"输出契约\"]\n    STREAM[\"流状态机\"]\n  end\n\n  CAPS --> COMPAT\n  CAPS --> TOOLS\n  CAPS --> OUTPUT\n  CAPS --> STREAM\n  HOOKS --> COMPAT\n  ACCESSORS --> STREAM\n\n  style ProviderSpec fill:#161b22,stroke:#30363d,color:#e6edf3\n  style BridgeKernel fill:#161b22,stroke:#6d5dfc,color:#e6edf3\n  style CAPS fill:#2d333b,stroke:#6d5dfc,color:#e6edf3\n  style ENDPOINT fill:#2d333b,stroke:#6d5dfc,color:#e6edf3\n  style HOOKS fill:#2d333b,stroke:#6d5dfc,color:#e6edf3\n  style ACCESSORS fill:#2d333b,stroke:#6d5dfc,color:#e6edf3\n  style COMPAT fill:#2d333b,stroke:#8b949e,color:#e6edf3\n  style TOOLS fill:#2d333b,stroke:#8b949e,color:#e6edf3\n  style OUTPUT fill:#2d333b,stroke:#8b949e,color:#e6edf3\n  style STREAM fill:#2d333b,stroke:#8b949e,color:#e6edf3\n```\n\n这种分离意味着添加新提供商不需要修改桥接内核。新提供商声明其支持的能力，内核自动适配。\n\n---\n\n## 风险评估\n\n### 技术风险\n\n| 风险 | 可能性 | 影响 | 缓解措施 |\n|------|-----------|--------|------------|\n| **协议漂移** -- OpenAI 以 GodeX 尚不支持的方式更改 Responses API | 中 | 高 | GodeX 将变更隔离在桥接内核内。代理代码和提供商规约不受影响。社区更新通常在 OpenAI 发布后数天内跟进。 |\n| **提供商 API 变更** -- 上游提供商修改其 Chat Completions 端点 | 中 | 中 | 提供商抽象将变更隔离到各个提供商钩子中。其他提供商不受影响。每个提供商规约是独立的。 |\n| **流式复杂性** -- SSE 状态机边界情况（不完整块、乱序事件、缺失终止事件） | 低 | 中 | 状态机具有明确的转换和终止状态验证。无效的流输出被重写为 `response.failed` 事件，而非静默损坏。 |\n| **结构化输出降级差距** -- JSON Schema 降级损失校验精度 | 低 | 低 | GodeX 验证输出是否为有效 JSON。不执行完整的 JSON Schema 一致性检查，但对大多数用例已足够。 |\n| **会话链损坏** -- 具有缺失父节点或循环的长链 | 低 | 中 | 内置循环检测、深度溢出保护和未完成响应处理。损坏的链返回结构化错误，而非静默失败。 |\n\n### 运维风险\n\n| 风险 | 可能性 | 影响 | 缓解措施 |\n|------|-----------|--------|------------|\n| **单点故障** -- GodeX 是单进程网关 | 中 | 高 | 在负载均衡器后部署多个实例。对于会话连续性，使用 SQLite 后端和粘性会话，或迁移到共享会话存储。 |\n| **延迟开销** -- GodeX 在代理和提供商之间增加处理 | 低 | 低 | 实测开销约为每请求 10-50ms，包括转换、兼容性规划和会话解析。远小于上游提供商延迟。 |\n| **会话存储扩展** -- 高并发下 SQLite 写入争用 | 低 | 中 | SQLite 能很好地处理并发读取。写入争用可通过 WAL 模式和批量追踪写入来缓解。对于非常高吞吐量，将会话迁移到外部数据库。 |\n| **配置错误** -- 无效的 godex.yaml 阻止启动 | 中 | 低 | 配置校验在启动时运行并给出清晰的错误消息。`godex config check` 可在不启动服务器的情况下验证配置。没有 `spec` 的旧版提供商配置会被明确拒绝。 |\n| **提供商凭证轮换** -- API 密钥过期或被撤销 | 中 | 中 | 环境变量插值（`${DEEPSEEK_API_KEY}`）支持标准密钥管理。目前密钥轮换需要重启。 |\n\n### 安全风险\n\n| 风险 | 可能性 | 影响 | 缓解措施 |\n|------|-----------|--------|------------|\n| **配置文件中 API 密钥泄露** | 中 | 高 | 使用环境变量插值。切勿将包含硬编码密钥的 `godex.yaml` 提交到版本控制。CI 管道应在部署时注入密钥。 |\n| **追踪载荷敏感性** -- 捕获的载荷包含完整的请求/响应文本 | 低 | 高 | 载荷捕获默认禁用（`trace.capture_payload: false`）。启用后，应将追踪数据库视为敏感数据。限制保留期限和访问权限。 |\n| **无客户端认证** -- 任何网络可达的客户端都可以使用网关 | 高 | 中 | 部署在带认证的反向代理之后。不要直接暴露在互联网上。这是生产部署中最高优先级的安全缺口。 |\n| **无速率限制** -- 网关接受无限制的请求 | 高 | 低 | 部署在带速率限制的反向代理之后。对于内部团队使用，风险较低。对于共享环境，添加外部速率限制。 |\n| **透传数据** -- GodeX 将所有请求内容转发给上游提供商 | 设计如此 | 取决于上下文 | GodeX 不检查、记录或修改超出协议转换范围的请求内容。组织必须信任其配置的上游提供商。 |\n\n---\n\n## 成本与扩展模型\n\n### 资源需求\n\nGodeX 被设计为轻量级单进程网关。与上游 LLM 提供商相比，资源消耗极少。\n\n| 资源 | 基线 | 每请求 | 扩展因子 |\n|----------|----------|-------------|----------------|\n| **CPU** | 空闲 <5% | 约 10-50ms 转换开销 | 与并发请求数成正比（事件循环模型） |\n| **内存** | 约 50MB 基础 | 每活跃会话约 1KB | 与会话存储大小和并发流连接数成正比 |\n| **磁盘** | 极少 | SQLite 写入用于会话和追踪 | 与请求量和追踪保留策略成正比 |\n| **网络** | 透传 | 与上游请求/响应相同 | 取决于上游提供商载荷大小 |\n\n### 延迟特征\n\n| 操作 | GodeX 开销 | 总计（典型） |\n|-----------|---------------|-----------------|\n| 请求解析和验证 | <1ms | -- |\n| 模型解析 | <1ms | -- |\n| 会话链查找（SQLite） | <10ms | -- |\n| 兼容性规划和请求构建 | <5ms | -- |\n| 提供商调用（网络） | 0ms（透传） | 500ms - 10s（取决于提供商） |\n| 响应重建 | <5ms | -- |\n| 追踪记录（异步批量） | 0ms（非阻塞） | -- |\n| **GodeX 总开销** | **约 10-50ms** | **远小于上游** |\n\n### 扩展限制\n\n| 维度 | 限制 | 策略 |\n|-----------|-------|----------|\n| 并发连接 | 单进程事件循环 | 垂直扩展足以满足单团队使用 |\n| 会话存储 | SQLite 单写入者 | WAL 模式用于读取并发；迁移到外部数据库以支持多写入者 |\n| 追踪吞吐量 | 批量异步写入 | 队列 + 刷新间隔（可配置） |\n| 水平扩展 | 实例间无共享状态 | 部署在带粘性会话的负载均衡器后；需要共享会话存储 |\n\n### 成本对比\n\n主要成本节省来自使用更便宜的提供商。GodeX 本身增加的基础设施成本可忽略不计。\n\n| 场景 | 没有 GodeX | 有 GodeX |\n|----------|--------------|------------|\n| 代理使用 OpenAI GPT-4 | 仅 OpenAI 定价 | -- |\n| 代理改用 DeepSeek | 定制集成工程成本 | 一次性 GodeX 设置 + DeepSeek 定价 |\n| 切换提供商 | 每个代理的代码更改 + 测试 | 更新 `godex.yaml` 中的一行配置 |\n| 多提供商支持 | N 倍集成工作量 | 单一网关，N 个提供商配置 |\n\n---\n\n## 技术栈\n\n| 技术 | 角色 | 选择理由 |\n|-----------|------|---------------|\n| **Bun 运行时** | 执行环境 | 原生 TypeScript、快速启动、单二进制编译、Web Streams API 支持 |\n| **TypeScript** | 编程语言 | 跨提供商规约的类型安全；严格模式搭配 `verbatimModuleSyntax` |\n| **SQLite (bun:sqlite)** | 会话和追踪持久化 | 零外部依赖、ACID 事务、进程内嵌入 |\n| **Web Streams API** | 流式管道 | 用于可组合 SSE 转换阶段的原生平台 API |\n| **Biome** | 代码检查和格式化 | 单一工具替代 ESLint + Prettier；基于 Rust 的高性能工具 |\n| **LogTape** | 结构化日志 | JSON 结构化日志，可配置级别和文件输出 |\n| **Commander.js** | CLI 框架 | 支持 `godex init`、`godex serve`、`godex config check` 命令 |\n| **Docker** | 容器化部署 | Docker Hub 和 GHCR 上的多架构镜像（amd64、arm64） |\n\n### 关键架构决策\n\n| 决策 | 理由 |\n|----------|-----------|\n| 基于规约的提供商模型 | 提供商声明能力而非实现。桥接内核集中规划兼容性。这防止了每个提供商的映射器丛林，保持代码库可维护。 |\n| 集中式桥接内核 | 所有 Responses 到 Chat 的策略都在 `src/bridge/` 中。提供商钩子仅暴露协议差异。这消除了跨提供商的重复兼容性决策。 |\n| SQLite 持久化 | 无外部数据库依赖。适合单网关部署。可替换为外部存储以支持水平扩展。 |\n| 领域错误层级 | 结构化错误码（server、bridge、provider、session）替代原始错误。每个预期失败都有领域码，使监控和告警更可靠。 |\n\n---\n\n## 提供商覆盖\n\n### 已支持的提供商\n\n| 提供商 | 默认模型 | 推理 | 工具选择 | 响应格式 | 缓存令牌 | 特别说明 |\n|----------|--------------|-----------|-------------|----------------|---------------|---------------|\n| **DeepSeek** | `deepseek-v4-pro` | 原生（high、max） | auto、none、required、function | text、json_object | 是 | 最适合高性价比编程。原生推理支持。 |\n| **Xiaomi / MiMo** | `mimo-v2.5-pro` | 布尔开关 | auto | text、json_object | 是 | 推理 via thinking 开关。最多 128 个工具。 |\n| **MiniMax** | `MiniMax-M3` | 布尔开关 | auto、none、required、function | text、json_object | 是 | 快速响应、图片/视频理解，以及完整的工具选择支持。 |\n| **Zhipu / ChatGLM** | `glm-5.2` | 布尔开关 | auto、none | text、json_object | 是 | 中国市场提供商。预配置编程端点。网页搜索工具支持。 |\n\n### 添加新提供商\n\n提供商规约模式专为可扩展性设计。新提供商需要：\n\n1. 一个 `ProviderSpec` 声明能力、端点和认证方案\n2. 用于请求修补和响应/流访问器的钩子\n3. 如果提供商的 Chat Completions 格式不同，需要协议特定的 DTO\n\n无需更改桥接内核、代理代码或其他提供商规约。\n\n---\n\n## 可观测性\n\n### 内置可观测性\n\n| 信号 | 来源 | 配置 |\n|--------|--------|---------------|\n| **健康端点** | `GET /health` | 始终可用。返回已注册和不支持的提供商。 |\n| **结构化日志** | LogTape JSON 日志器 | 级别可通过 `godex.yaml` 配置。控制台和文件输出。 |\n| **请求追踪** | SQLite 追踪数据库 | 默认启用。记录请求元数据、用量、事件和错误。 |\n| **载荷捕获** | 追踪子系统 | 默认禁用。启用 `trace.capture_payload: true` 用于调试。视为敏感数据。 |\n| **错误领域码** | GodeXError 层级 | 每个预期失败映射到领域码：`server.*`、`bridge.*`、`provider.*`、`session.*` |\n| **用量追踪** | 每响应 `usage` 字段 | 输入令牌、输出令牌、缓存令牌、推理令牌。 |\n\n### 尚未建设的部分\n\n| 缺口 | 影响 | 优先级 |\n|-----|--------|----------|\n| 无 Prometheus/OpenTelemetry 指标 | 无法与标准可观测性栈集成 | 中 |\n| 无用于配置重载的管理 API | 提供商变更需要重启 | 中 |\n| 无仪表板或 UI | 追踪数据需要直接查询 SQLite | 低 |\n\n---\n\n## 团队上手\n\n### 产出价值所需时间\n\n| 角色 | 首次产出价值时间 | 路径 |\n|------|-------------------|------|\n| 使用 GodeX 的开发者 | 15 分钟 | 安装、运行 `godex init`、配置一个提供商、将代理指向 GodeX |\n| 部署 GodeX 的运维人员 | 30 分钟 | Docker 拉取、创建 `godex.yaml`、使用环境变量部署 API 密钥 |\n| 添加提供商的贡献者 | 2-4 小时 | 研究现有提供商规约模式，实现规约 + 钩子 + 测试 |\n| 修改桥接内核的贡献者 | 1-2 天 | 理解兼容性规划器、工具规划器、流状态机 |\n\n### 上手路径\n\n| 如果你是... | 阅读这个... |\n|---------------|-------------|\n| 为团队设置 GodeX 的开发者 | Getting Started 指南 |\n| 加入项目的贡献者 | [贡献者指南](./contributor-guide.md) |\n| 评估架构决策的主任工程师 | [主任工程师指南](./staff-engineer-guide.md) |\n| 了解功能的产品经理 | [产品经理指南](./product-manager-guide.md) |\n\n---\n\n## 建议\n\n基于 GodeX 的当前状态，以下建议按优先级排列供领导层参考：\n\n### 1. 在面向生产环境之前添加客户端认证\n\nGodeX 没有内置认证。在将网关暴露到受信任的内部网络之外之前，至少实现一个 API 密钥检查。这是最高优先级的安全缺口。带认证的反向代理是可接受的临时解决方案。\n\n### 2. 添加 Prometheus 指标以实现生产可观测性\n\n标准指标 -- 请求延迟直方图、按提供商的错误率、上游延迟、会话存储大小、追踪队列深度 -- 将无需定制工具即可实现生产监控。这是最高优先级的可观测性缺口。\n\n### 3. 实现速率限制\n\n在多团队或外部访问之前，添加速率限制。这可以防止单个配置错误的代理消耗所有网关容量。通过反向代理的外部速率限制是可接受的。\n\n### 4. 规划水平扩展\n\n目前，GodeX 是带有本地会话存储的单进程网关。对于多团队部署，规划共享会话存储（Redis 或 PostgreSQL）以在负载均衡器后实现水平扩展，无需粘性会话。\n\n### 5. 主动扩展提供商覆盖\n\n基于规约的架构使添加提供商变得低成本。随着采纳增长，主动添加团队请求的提供商。每个新提供商都在不增加消费者集成复杂度的情况下提升网关价值。\n\n---\n\n## 总结\n\nGodeX 提供了一项聚焦的高价值能力：让 AI 编程代理通过单一 OpenAI 兼容网关使用任何 Chat Completions 提供商。架构清晰，提供商模型可扩展，运维开销最小。\n\n主要风险是运维层面的（单点故障、无认证、无速率限制）而非技术层面的。这些可以通过标准基础设施模式解决，无需更改 GodeX 本身。\n\n投资逻辑直截了当：减少供应商锁定、实现成本优化、提供中国市场接入 -- 所有这些都无需修改代理代码。\n\n---\n\n[贡献者指南](./contributor-guide.md) · [主任工程师指南](./staff-engineer-guide.md) · [产品经理指南](./product-manager-guide.md) · [上手索引](./index.md)\n"}}, "godex.deepseek.yaml": {"e43ccea40d40691f1fbd146fd356f5b0d79b5eb7": {"t": 1785745199.3039432, "n": 1225, "h": "0dfbfb10b42234f9", "c": "# =============================================================================\n# GodeX Configuration — DeepSeek Provider\n# =============================================================================\n# 快速启动: godex serve --config ./godex.deepseek.yaml\n# 环境变量: export DEEPSEEK_API_KEY=<your-key>\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    # -------------------------------------------------------------------------\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n    gpt-5.4-mini: \"deepseek/deepseek-v4-flash\"\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n    gpt-5.3-codex-spark: \"deepseek/deepseek-v4-flash\"\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n\nsession:\n  backend: sqlite\n  sqlite:\n    path: ./data/sessions.deepseek.db\n\ntrace:\n  enabled: true\n  path: ./data/trace.deepseek.db\n  capture_payload: true\n  payload_max_bytes: 1048576\n"}, "987f4ae12bd1372136723ad78a3ac73587783fbc": {"t": 1785748563.4681735, "n": 1225, "h": "0dfbfb10b42234f9", "c": "# =============================================================================\n# GodeX Configuration — DeepSeek Provider\n# =============================================================================\n# 快速启动: godex serve --config ./godex.deepseek.yaml\n# 环境变量: export DEEPSEEK_API_KEY=<your-key>\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    # -------------------------------------------------------------------------\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n    gpt-5.4-mini: \"deepseek/deepseek-v4-flash\"\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n    gpt-5.3-codex-spark: \"deepseek/deepseek-v4-flash\"\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n\nsession:\n  backend: sqlite\n  sqlite:\n    path: ./data/sessions.deepseek.db\n\ntrace:\n  enabled: true\n  path: ./data/trace.deepseek.db\n  capture_payload: true\n  payload_max_bytes: 1048576\n"}, "a8af5f8b9bdb48050a26dbb64721c2d81f8431ba": {"t": 1785748564.5124085, "n": 714, "h": "7c19f2b47d82bf0c", "c": "# =============================================================================\n# GodeX Configuration — DeepSeek Provider\n# =============================================================================\n# 快速启动: godex serve --config ./godex.deepseek.yaml\n# 环境变量: export DEEPSEEK_API_KEY=<your-key>\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    \"*\": deepseek/deepseek-v4-pro\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n\nsession:\n  backend: sqlite\n  sqlite:\n    path: ./data/sessions.deepseek.db\n\ntrace:\n  enabled: true\n  path: ./data/trace.deepseek.db\n  capture_payload: true\n  payload_max_bytes: 1048576\n"}, "9efb5d28b803166fc52e46da8d469512befd054b": {"t": 1786067306.526842, "n": 1225, "h": "0dfbfb10b42234f9", "c": "# =============================================================================\n# GodeX Configuration — DeepSeek Provider\n# =============================================================================\n# 快速启动: godex serve --config ./godex.deepseek.yaml\n# 环境变量: export DEEPSEEK_API_KEY=<your-key>\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    # -------------------------------------------------------------------------\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n    gpt-5.4-mini: \"deepseek/deepseek-v4-flash\"\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n    gpt-5.3-codex-spark: \"deepseek/deepseek-v4-flash\"\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n\nsession:\n  backend: sqlite\n  sqlite:\n    path: ./data/sessions.deepseek.db\n\ntrace:\n  enabled: true\n  path: ./data/trace.deepseek.db\n  capture_payload: true\n  payload_max_bytes: 1048576\n"}, "e4b02fa899c22db59bd7a257edccad7d2aae168d": {"t": 1786068205.6284347, "n": 1225, "h": "0dfbfb10b42234f9", "c": "# =============================================================================\n# GodeX Configuration — DeepSeek Provider\n# =============================================================================\n# 快速启动: godex serve --config ./godex.deepseek.yaml\n# 环境变量: export DEEPSEEK_API_KEY=<your-key>\n\ndefault_provider: deepseek\n\nmodels:\n  aliases:\n    # -------------------------------------------------------------------------\n    # Codex-compatible model aliases\n    # -------------------------------------------------------------------------\n    gpt-5.5: \"deepseek/deepseek-v4-pro\"\n    gpt-5.4: \"deepseek/deepseek-v4-pro\"\n    gpt-5.4-mini: \"deepseek/deepseek-v4-flash\"\n    gpt-5.3-codex: \"deepseek/deepseek-v4-pro\"\n    gpt-5.3-codex-spark: \"deepseek/deepseek-v4-flash\"\n    gpt-5.2: \"deepseek/deepseek-v4-pro\"\n\n    # Fallback for unknown bare model names\n    \"*\": \"deepseek/deepseek-v4-pro\"\n\nproviders:\n  deepseek:\n    spec: deepseek\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n\nsession:\n  backend: sqlite\n  sqlite:\n    path: ./data/sessions.deepseek.db\n\ntrace:\n  enabled: true\n  path: ./data/trace.deepseek.db\n  capture_payload: true\n  payload_max_bytes: 1048576\n"}}, "wiki/07-configuration/config-schema.md": {"65e82bfe593cda21c1ea3f408546df5519d939a1": {"t": 1785746654.0215466, "n": 10744, "h": "f36cdc59376ddb81", "c": "---\ntitle: \"Config Schema\"\ndescription: \"Complete reference for godex.yaml configuration options.\"\nkeywords: \"GodeX, config schema, godex.yaml, YAML, server, providers, session\"\n---\n\n# Config Schema\n\nGodeX is configured via a `godex.yaml` file, typically created by `godex init`. Environment variables are interpolated using `${VAR_NAME}` syntax.\n\n## Full Schema\n\n```yaml\nserver:\n  port: 5678              # HTTP listen port\n  host: \"0.0.0.0\"         # Listen address\n  idle_timeout: 30000     # Idle connection timeout (ms)\n                         # Default: 0 (disabled)\n\ndefault_provider: deepseek   # Provider used when model has no slash prefix\n\nmodels:\n  aliases:\n    \"gpt-5.5\": deepseek/deepseek-v4-pro   # Maps alias to provider/model\n    \"glm\": zhipu/glm-5.1                   # Maps alias to provider/model\n    \"*\": deepseek/deepseek-v4-flash        # Catch-all fallback\n\nproviders:\n  deepseek:\n    spec: deepseek                      # Provider spec name (required)\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n    timeout_ms: 30000\n\n  zhipu:\n    spec: zhipu                         # Provider spec name (required)\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    timeout_ms: 30000\n\n  minimax:\n    spec: minimax                        # Provider spec name (required)\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n    timeout_ms: 30000\n\nsession:\n  backend: sqlite         # \"sqlite\" or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info             # trace | debug | info | warn | error\n  console:\n    enabled: true\n    level: info\n  file:\n    enabled: false\n    level: debug\n    dir: ./logs\n    filename: godex.log\n    max_size: 10485760    # 10MB\n    max_files: 5\n\nweb_search:                      # Built-in web search (default: enabled, no provider)\n  enabled: true                  # Master switch\n  mode: auto                     # auto | provider_native | godex_managed | disabled\n  provider: none                 # none | mock | zhipu (search backend for godex_managed)\n  on_unavailable: client_tool_call  # client_tool_call | fail | ignore\n  max_iterations: 2              # Max managed search rounds per request\n  timeout_ms: 10000              # Per-search timeout\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  max_queue_size: 10000\n  flush_interval_ms: 1000\n  batch_size: 100\n  capture_payload: false\n  payload_max_bytes: 65536\n```\n\n## Type Definitions\n\n```mermaid\nclassDiagram\n\n  class GodeXConfig {\n    +server: ServerConfig\n    +default_provider: string\n    +models: ModelsConfig\n    +providers: Record~string, ProviderConfig~\n    +session: SessionConfig\n    +logging: LoggingConfig\n    +web_search: WebSearchConfig\n    +trace: TraceConfig\n  }\n\n  class ServerConfig {\n    +port: number\n    +host: string\n    +idle_timeout: number\n  }\n\n  class ProviderConfig {\n    +spec: string\n    +credentials: CredentialsConfig\n    +endpoint: EndpointConfig\n    +timeout_ms: number\n  }\n\n  class CredentialsConfig {\n    +api_key: string\n  }\n\n  class EndpointConfig {\n    +base_url: string\n  }\n\n  class ModelsConfig {\n    +aliases: Record~string, string~\n  }\n\n  class SessionConfig {\n    +backend: string\n    +sqlite: SQLiteConfig\n  }\n\n  class LoggingConfig {\n    +level: LogLevel\n    +console: ConsoleLoggingConfig\n    +file: FileLoggingConfig\n  }\n\n  class TraceConfig {\n    +enabled: boolean\n    +path: string\n    +max_queue_size: number\n    +flush_interval_ms: number\n    +batch_size: number\n    +capture_payload: boolean\n    +payload_max_bytes: number\n  }\n\n  class WebSearchConfig {\n    +enabled: boolean\n    +mode: WebSearchMode\n    +provider: WebSearchProvider\n    +on_unavailable: WebSearchOnUnavailable\n    +max_iterations: number\n    +timeout_ms: number\n  }\n\n  GodeXConfig --> ServerConfig\n  GodeXConfig --> ModelsConfig\n  GodeXConfig --> ProviderConfig\n  GodeXConfig --> SessionConfig\n  GodeXConfig --> LoggingConfig\n  GodeXConfig --> WebSearchConfig\n  GodeXConfig --> TraceConfig\n  ProviderConfig --> CredentialsConfig\n  ProviderConfig --> EndpointConfig\n```\n\n## Provider Config\n\nEach provider entry must include a `spec` field that matches a registered provider definition name. Legacy provider config without `spec` is rejected at startup.\n\n```yaml\nproviders:\n  myprovider:\n    spec: myprovider           # Required: matches registered definition\n    credentials:\n      api_key: ${MY_API_KEY}\n    endpoint:\n      base_url: https://api.example.com/v1\n    timeout_ms: 30000\n```\n\n## Web Search\n\nGodeX can run web search in two ways: let the provider handle it natively, or run the search itself (\"GodeX-managed\" / \"hosted\") and feed results back into a continuation request. The `web_search` block ([src/config/sections/web-search.ts:10](https://github.com/Ahoo-Wang/GodeX/blob/main/src/config/sections/web-search.ts#L10)) controls this.\n\n::: warning Important: native providers always use native search\nFor providers whose tool set already includes `web_search` as a native tool (Zhipu, Xiaomi), the planner returns the tool as natively supported **before** consulting `mode`. This means `mode: godex_managed` and `mode: disabled` have **no effect** on those providers — they always get native `web_search`. The `mode` settings below govern how `web_search` is handled for providers that do **not** support it natively (DeepSeek, MiniMax), or when you want GodeX to host the search loop. See [tool-plan.ts:129](https://github.com/Ahoo-Wang/GodeX/blob/main/src/bridge/tools/tool-plan.ts#L129) for the precedence (native → degraded → web-search planning).\n:::\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `enabled` | `true` | Master switch. When `false`, the effective `mode` becomes `disabled` and `available` is `false`. |\n| `mode` | `auto` | Execution strategy — see the table below (applies to non-native providers). |\n| `provider` | `none` | The search backend GodeX uses in `godex_managed` mode. |\n| `on_unavailable` | `client_tool_call` | What to do when managed search is selected but no backend is available. |\n| `max_iterations` | `2` | Maximum number of managed search rounds per request. |\n| `timeout_ms` | `10000` | Per-search timeout in milliseconds. |\n\n### `mode` — execution strategy\n\nThese modes apply to providers that do **not** support `web_search` natively. The planner ([tool-plan.ts:164](https://github.com/Ahoo-Wang/GodeX/blob/main/src/bridge/tools/tool-plan.ts#L164)) reaches web-search planning only after the native and degraded checks, so for native providers the tool is always handled by the provider regardless of `mode`.\n\n| Mode | Behavior (non-native providers) |\n|------|----------|\n| `auto` | If a search `provider` backend is `available`, GodeX hosts the search loop (managed); otherwise the `on_unavailable` policy applies. |\n| `provider_native` | Declares the tool with provider-native execution. For providers without native `web_search`, this falls through to web-search planning like `auto`. |\n| `godex_managed` | GodeX intercepts the `web_search` function call, runs the search itself via the configured `provider` backend, emits the `web_search_call` lifecycle (`in_progress` → `searching` → `completed` / failed), and submits a continuation request with the results. Up to `max_iterations` rounds. If no backend is `available`, the `on_unavailable` policy applies. |\n| `disabled` | The managed loop is not offered. For non-native providers the `on_unavailable` policy still applies (default `client_tool_call`), so a search tool may still be exposed as a client-visible function call — set `on_unavailable: ignore` (or `fail`) to suppress it entirely. |\n\n### `provider` — managed search backend\n\n| Provider | Description |\n|----------|-------------|\n| `none` | No backend. Managed search is unavailable (`available` is `false`); the `on_unavailable` policy then applies. |\n| `mock` | Returns canned results; used for testing. |\n| `zhipu` | [Zhipu Web Search API](https://open.bigmodel.cn/dev/api/search-tool/websearch). |\n\n::: warning The Zhipu search backend reads the provider config, not just env\nSelecting `provider: zhipu` makes the backend `available` only when a `providers.zhipu` block with a `credentials.api_key` exists in `godex.yaml` — `createSearchService` reads `config.providers.zhipu.credentials.api_key` ([search/registry.ts:16-17](https://github.com/Ahoo-Wang/GodeX/blob/main/src/search/registry.ts#L16-L17)) and falls back to a no-op provider when it is absent. So on a DeepSeek/MiniMax-only config, exporting `ZHIPU_API_KEY` alone is **not** enough; add a full `providers.zhipu` entry (env interpolation works, e.g. `api_key: ${ZHIPU_API_KEY}`), or GodeX will take the `on_unavailable` path instead of hosting search.\n:::\n\n### `on_unavailable` — fallback policy\n\nApplies when the managed search loop is selected (`mode` is `auto`/`godex_managed`) but no backend is `available`, as well as when `mode` is `disabled` for a non-native provider.\n\n| Policy | Behavior |\n|--------|----------|\n| `client_tool_call` | Forward the `web_search` call to the client as a normal function call (the client handles it). |\n| `fail` | Fail the request with a `BridgeError`. |\n| `ignore` | Silently drop the search call. |\n\n::: tip\nWith the shipped defaults (`mode: auto`, `provider: none`), providers that support native web search (Zhipu, Xiaomi) use it directly, while other providers forward `web_search` calls to the client. To enable GodeX-managed search for **non-native** providers, set `provider: zhipu` **and** add a `providers.zhipu` block (with `credentials.api_key`) to `godex.yaml` — see the warning above.\n:::\n\nThe managed search loop is implemented by `HostedWebSearchStreamRunner` / `HostedWebSearchSyncRunner` in `src/responses/web-search/`. See [Streaming Pipeline](../02-architecture/streaming-pipeline.md) for how it integrates into the event production stage.\n\n## Environment Interpolation\n\nValues like `${DEEPSEEK_API_KEY}` are resolved at load time from environment variables. Missing variables produce a startup error.\n\n## Environment Variable Overrides\n\nBESIDES YAML interpolation, these environment variables directly override config fields at load time (CLI flags take precedence over both):\n\n| Variable | Config Field | Notes |\n|----------|-------------|-------|\n| `GODEX_PORT` | `server.port` | Overrides the listen port |\n| `GODEX_HOST` | `server.host` | Overrides the bind address |\n| `GODEX_LOG_LEVEL` | `logging.level` | Overrides the log level |\n| `GODEX_DEFAULT_PROVIDER` | `default_provider` | Falls back to `deepseek` if both are unset |\n\n[CLI Commands](/07-configuration/cli-commands)\n\n"}, "c217c43a4664eb50c292f8d9f3a9aaa4b24ccbe2": {"t": 1785748564.2147558, "n": 10744, "h": "f36cdc59376ddb81", "c": "---\ntitle: \"Config Schema\"\ndescription: \"Complete reference for godex.yaml configuration options.\"\nkeywords: \"GodeX, config schema, godex.yaml, YAML, server, providers, session\"\n---\n\n# Config Schema\n\nGodeX is configured via a `godex.yaml` file, typically created by `godex init`. Environment variables are interpolated using `${VAR_NAME}` syntax.\n\n## Full Schema\n\n```yaml\nserver:\n  port: 5678              # HTTP listen port\n  host: \"0.0.0.0\"         # Listen address\n  idle_timeout: 30000     # Idle connection timeout (ms)\n                         # Default: 0 (disabled)\n\ndefault_provider: deepseek   # Provider used when model has no slash prefix\n\nmodels:\n  aliases:\n    \"gpt-5.5\": deepseek/deepseek-v4-pro   # Maps alias to provider/model\n    \"glm\": zhipu/glm-5.1                   # Maps alias to provider/model\n    \"*\": deepseek/deepseek-v4-flash        # Catch-all fallback\n\nproviders:\n  deepseek:\n    spec: deepseek                      # Provider spec name (required)\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n    timeout_ms: 30000\n\n  zhipu:\n    spec: zhipu                         # Provider spec name (required)\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    timeout_ms: 30000\n\n  minimax:\n    spec: minimax                        # Provider spec name (required)\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n    timeout_ms: 30000\n\nsession:\n  backend: sqlite         # \"sqlite\" or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info             # trace | debug | info | warn | error\n  console:\n    enabled: true\n    level: info\n  file:\n    enabled: false\n    level: debug\n    dir: ./logs\n    filename: godex.log\n    max_size: 10485760    # 10MB\n    max_files: 5\n\nweb_search:                      # Built-in web search (default: enabled, no provider)\n  enabled: true                  # Master switch\n  mode: auto                     # auto | provider_native | godex_managed | disabled\n  provider: none                 # none | mock | zhipu (search backend for godex_managed)\n  on_unavailable: client_tool_call  # client_tool_call | fail | ignore\n  max_iterations: 2              # Max managed search rounds per request\n  timeout_ms: 10000              # Per-search timeout\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  max_queue_size: 10000\n  flush_interval_ms: 1000\n  batch_size: 100\n  capture_payload: false\n  payload_max_bytes: 65536\n```\n\n## Type Definitions\n\n```mermaid\nclassDiagram\n\n  class GodeXConfig {\n    +server: ServerConfig\n    +default_provider: string\n    +models: ModelsConfig\n    +providers: Record~string, ProviderConfig~\n    +session: SessionConfig\n    +logging: LoggingConfig\n    +web_search: WebSearchConfig\n    +trace: TraceConfig\n  }\n\n  class ServerConfig {\n    +port: number\n    +host: string\n    +idle_timeout: number\n  }\n\n  class ProviderConfig {\n    +spec: string\n    +credentials: CredentialsConfig\n    +endpoint: EndpointConfig\n    +timeout_ms: number\n  }\n\n  class CredentialsConfig {\n    +api_key: string\n  }\n\n  class EndpointConfig {\n    +base_url: string\n  }\n\n  class ModelsConfig {\n    +aliases: Record~string, string~\n  }\n\n  class SessionConfig {\n    +backend: string\n    +sqlite: SQLiteConfig\n  }\n\n  class LoggingConfig {\n    +level: LogLevel\n    +console: ConsoleLoggingConfig\n    +file: FileLoggingConfig\n  }\n\n  class TraceConfig {\n    +enabled: boolean\n    +path: string\n    +max_queue_size: number\n    +flush_interval_ms: number\n    +batch_size: number\n    +capture_payload: boolean\n    +payload_max_bytes: number\n  }\n\n  class WebSearchConfig {\n    +enabled: boolean\n    +mode: WebSearchMode\n    +provider: WebSearchProvider\n    +on_unavailable: WebSearchOnUnavailable\n    +max_iterations: number\n    +timeout_ms: number\n  }\n\n  GodeXConfig --> ServerConfig\n  GodeXConfig --> ModelsConfig\n  GodeXConfig --> ProviderConfig\n  GodeXConfig --> SessionConfig\n  GodeXConfig --> LoggingConfig\n  GodeXConfig --> WebSearchConfig\n  GodeXConfig --> TraceConfig\n  ProviderConfig --> CredentialsConfig\n  ProviderConfig --> EndpointConfig\n```\n\n## Provider Config\n\nEach provider entry must include a `spec` field that matches a registered provider definition name. Legacy provider config without `spec` is rejected at startup.\n\n```yaml\nproviders:\n  myprovider:\n    spec: myprovider           # Required: matches registered definition\n    credentials:\n      api_key: ${MY_API_KEY}\n    endpoint:\n      base_url: https://api.example.com/v1\n    timeout_ms: 30000\n```\n\n## Web Search\n\nGodeX can run web search in two ways: let the provider handle it natively, or run the search itself (\"GodeX-managed\" / \"hosted\") and feed results back into a continuation request. The `web_search` block ([src/config/sections/web-search.ts:10](https://github.com/Ahoo-Wang/GodeX/blob/main/src/config/sections/web-search.ts#L10)) controls this.\n\n::: warning Important: native providers always use native search\nFor providers whose tool set already includes `web_search` as a native tool (Zhipu, Xiaomi), the planner returns the tool as natively supported **before** consulting `mode`. This means `mode: godex_managed` and `mode: disabled` have **no effect** on those providers — they always get native `web_search`. The `mode` settings below govern how `web_search` is handled for providers that do **not** support it natively (DeepSeek, MiniMax), or when you want GodeX to host the search loop. See [tool-plan.ts:129](https://github.com/Ahoo-Wang/GodeX/blob/main/src/bridge/tools/tool-plan.ts#L129) for the precedence (native → degraded → web-search planning).\n:::\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `enabled` | `true` | Master switch. When `false`, the effective `mode` becomes `disabled` and `available` is `false`. |\n| `mode` | `auto` | Execution strategy — see the table below (applies to non-native providers). |\n| `provider` | `none` | The search backend GodeX uses in `godex_managed` mode. |\n| `on_unavailable` | `client_tool_call` | What to do when managed search is selected but no backend is available. |\n| `max_iterations` | `2` | Maximum number of managed search rounds per request. |\n| `timeout_ms` | `10000` | Per-search timeout in milliseconds. |\n\n### `mode` — execution strategy\n\nThese modes apply to providers that do **not** support `web_search` natively. The planner ([tool-plan.ts:164](https://github.com/Ahoo-Wang/GodeX/blob/main/src/bridge/tools/tool-plan.ts#L164)) reaches web-search planning only after the native and degraded checks, so for native providers the tool is always handled by the provider regardless of `mode`.\n\n| Mode | Behavior (non-native providers) |\n|------|----------|\n| `auto` | If a search `provider` backend is `available`, GodeX hosts the search loop (managed); otherwise the `on_unavailable` policy applies. |\n| `provider_native` | Declares the tool with provider-native execution. For providers without native `web_search`, this falls through to web-search planning like `auto`. |\n| `godex_managed` | GodeX intercepts the `web_search` function call, runs the search itself via the configured `provider` backend, emits the `web_search_call` lifecycle (`in_progress` → `searching` → `completed` / failed), and submits a continuation request with the results. Up to `max_iterations` rounds. If no backend is `available`, the `on_unavailable` policy applies. |\n| `disabled` | The managed loop is not offered. For non-native providers the `on_unavailable` policy still applies (default `client_tool_call`), so a search tool may still be exposed as a client-visible function call — set `on_unavailable: ignore` (or `fail`) to suppress it entirely. |\n\n### `provider` — managed search backend\n\n| Provider | Description |\n|----------|-------------|\n| `none` | No backend. Managed search is unavailable (`available` is `false`); the `on_unavailable` policy then applies. |\n| `mock` | Returns canned results; used for testing. |\n| `zhipu` | [Zhipu Web Search API](https://open.bigmodel.cn/dev/api/search-tool/websearch). |\n\n::: warning The Zhipu search backend reads the provider config, not just env\nSelecting `provider: zhipu` makes the backend `available` only when a `providers.zhipu` block with a `credentials.api_key` exists in `godex.yaml` — `createSearchService` reads `config.providers.zhipu.credentials.api_key` ([search/registry.ts:16-17](https://github.com/Ahoo-Wang/GodeX/blob/main/src/search/registry.ts#L16-L17)) and falls back to a no-op provider when it is absent. So on a DeepSeek/MiniMax-only config, exporting `ZHIPU_API_KEY` alone is **not** enough; add a full `providers.zhipu` entry (env interpolation works, e.g. `api_key: ${ZHIPU_API_KEY}`), or GodeX will take the `on_unavailable` path instead of hosting search.\n:::\n\n### `on_unavailable` — fallback policy\n\nApplies when the managed search loop is selected (`mode` is `auto`/`godex_managed`) but no backend is `available`, as well as when `mode` is `disabled` for a non-native provider.\n\n| Policy | Behavior |\n|--------|----------|\n| `client_tool_call` | Forward the `web_search` call to the client as a normal function call (the client handles it). |\n| `fail` | Fail the request with a `BridgeError`. |\n| `ignore` | Silently drop the search call. |\n\n::: tip\nWith the shipped defaults (`mode: auto`, `provider: none`), providers that support native web search (Zhipu, Xiaomi) use it directly, while other providers forward `web_search` calls to the client. To enable GodeX-managed search for **non-native** providers, set `provider: zhipu` **and** add a `providers.zhipu` block (with `credentials.api_key`) to `godex.yaml` — see the warning above.\n:::\n\nThe managed search loop is implemented by `HostedWebSearchStreamRunner` / `HostedWebSearchSyncRunner` in `src/responses/web-search/`. See [Streaming Pipeline](../02-architecture/streaming-pipeline.md) for how it integrates into the event production stage.\n\n## Environment Interpolation\n\nValues like `${DEEPSEEK_API_KEY}` are resolved at load time from environment variables. Missing variables produce a startup error.\n\n## Environment Variable Overrides\n\nBESIDES YAML interpolation, these environment variables directly override config fields at load time (CLI flags take precedence over both):\n\n| Variable | Config Field | Notes |\n|----------|-------------|-------|\n| `GODEX_PORT` | `server.port` | Overrides the listen port |\n| `GODEX_HOST` | `server.host` | Overrides the bind address |\n| `GODEX_LOG_LEVEL` | `logging.level` | Overrides the log level |\n| `GODEX_DEFAULT_PROVIDER` | `default_provider` | Falls back to `deepseek` if both are unset |\n\n[CLI Commands](/07-configuration/cli-commands)\n\n"}, "99a9b18d2a91596af8525a615eb05796344e813f": {"t": 1785748565.3487267, "n": 4586, "h": "f7040cf9a4cd92d1", "c": "---\ntitle: \"Config Schema\"\ndescription: \"Complete reference for godex.yaml configuration options.\"\nkeywords: \"GodeX, config schema, godex.yaml, YAML, server, providers, session\"\n---\n\n# Config Schema\n\nGodeX is configured via a `godex.yaml` file, typically created by `godex init`. Environment variables are interpolated using `${VAR_NAME}` syntax.\n\n## Full Schema\n\n```yaml\nserver:\n  port: 5678              # HTTP listen port\n  host: \"0.0.0.0\"         # Listen address\n  idle_timeout: 30000     # Idle connection timeout (ms)\n                         # Default: 0 (disabled)\n\ndefault_provider: deepseek   # Provider used when model has no slash prefix\n\nmodels:\n  aliases:\n    \"gpt-5.5\": deepseek/deepseek-v4-pro   # Maps alias to provider/model\n    \"glm\": zhipu/glm-5.1                   # Maps alias to provider/model\n    \"*\": deepseek/deepseek-v4-flash        # Catch-all fallback\n\nproviders:\n  deepseek:\n    spec: deepseek                      # Provider spec name (required)\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n    timeout_ms: 30000\n\n  zhipu:\n    spec: zhipu                         # Provider spec name (required)\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    timeout_ms: 30000\n\n  minimax:\n    spec: minimax                        # Provider spec name (required)\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n    timeout_ms: 30000\n\nsession:\n  backend: sqlite         # \"sqlite\" or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info             # trace | debug | info | warn | error\n  console:\n    enabled: true\n    level: info\n  file:\n    enabled: false\n    level: debug\n    dir: ./logs\n    filename: godex.log\n    max_size: 10485760    # 10MB\n    max_files: 5\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  max_queue_size: 10000\n  flush_interval_ms: 1000\n  batch_size: 100\n  capture_payload: false\n  payload_max_bytes: 65536\n```\n\n## Type Definitions\n\n```mermaid\nclassDiagram\n\n  class GodeXConfig {\n    +server: ServerConfig\n    +default_provider: string\n    +models: ModelsConfig\n    +providers: Record~string, ProviderConfig~\n    +session: SessionConfig\n    +logging: LoggingConfig\n    +trace: TraceConfig\n  }\n\n  class ServerConfig {\n    +port: number\n    +host: string\n    +idle_timeout: number\n  }\n\n  class ProviderConfig {\n    +spec: string\n    +credentials: CredentialsConfig\n    +endpoint: EndpointConfig\n    +timeout_ms: number\n  }\n\n  class CredentialsConfig {\n    +api_key: string\n  }\n\n  class EndpointConfig {\n    +base_url: string\n  }\n\n  class ModelsConfig {\n    +aliases: Record~string, string~\n  }\n\n  class SessionConfig {\n    +backend: string\n    +sqlite: SQLiteConfig\n  }\n\n  class LoggingConfig {\n    +level: LogLevel\n    +console: ConsoleLoggingConfig\n    +file: FileLoggingConfig\n  }\n\n  class TraceConfig {\n    +enabled: boolean\n    +path: string\n    +max_queue_size: number\n    +flush_interval_ms: number\n    +batch_size: number\n    +capture_payload: boolean\n    +payload_max_bytes: number\n  }\n\n  GodeXConfig --> ServerConfig\n  GodeXConfig --> ModelsConfig\n  GodeXConfig --> ProviderConfig\n  GodeXConfig --> SessionConfig\n  GodeXConfig --> LoggingConfig\n  GodeXConfig --> TraceConfig\n  ProviderConfig --> CredentialsConfig\n  ProviderConfig --> EndpointConfig\n```\n\n## Provider Config\n\nEach provider entry must include a `spec` field that matches a registered provider definition name. Legacy provider config without `spec` is rejected at startup.\n\n```yaml\nproviders:\n  myprovider:\n    spec: myprovider           # Required: matches registered definition\n    credentials:\n      api_key: ${MY_API_KEY}\n    endpoint:\n      base_url: https://api.example.com/v1\n    timeout_ms: 30000\n```\n\n## Environment Interpolation\n\nValues like `${DEEPSEEK_API_KEY}` are resolved at load time from environment variables. Missing variables produce a startup error.\n\n## Environment Variable Overrides\n\nBESIDES YAML interpolation, these environment variables directly override config fields at load time (CLI flags take precedence over both):\n\n| Variable | Config Field | Notes |\n|----------|-------------|-------|\n| `GODEX_PORT` | `server.port` | Overrides the listen port |\n| `GODEX_HOST` | `server.host` | Overrides the bind address |\n| `GODEX_LOG_LEVEL` | `logging.level` | Overrides the log level |\n| `GODEX_DEFAULT_PROVIDER` | `default_provider` | Falls back to `deepseek` if both are unset |\n\n[CLI Commands](/07-configuration/cli-commands)\n\n"}, "a8af5f8b9bdb48050a26dbb64721c2d81f8431ba": {"t": 1785748566.4075866, "n": 4600, "h": "fd54e5799f19c89b", "c": "---\ntitle: \"Config Schema\"\ndescription: \"Complete reference for godex.yaml configuration options.\"\nkeywords: \"GodeX, config schema, godex.yaml, YAML, server, providers, session\"\n---\n\n# Config Schema\n\nGodeX is configured via a `godex.yaml` file, typically created by `godex init`. Environment variables are interpolated using `${VAR_NAME}` syntax.\n\n## Full Schema\n\n```yaml\nserver:\n  port: 5678              # HTTP listen port\n  host: \"0.0.0.0\"         # Listen address\n  idle_timeout: 30000     # Idle connection timeout (ms)\n                         # Default: 0 (disabled)\n\ndefault_provider: deepseek   # Provider used when model has no slash prefix\n\nmodels:\n  aliases:\n    \"gpt-5.5\": deepseek/deepseek-v4-pro   # Maps alias to provider/model\n    \"glm\": zhipu/glm-5.1                   # Maps alias to provider/model\n    \"*\": deepseek/deepseek-v4-flash        # Catch-all fallback\n\nproviders:\n  deepseek:\n    spec: deepseek                      # Provider spec name (required)\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n    timeout_ms: 30000\n\n  zhipu:\n    spec: zhipu                         # Provider spec name (required)\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    timeout_ms: 30000\n\n  minimax:\n    spec: minimax                        # Provider spec name (required)\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n    timeout_ms: 30000\n\nsession:\n  backend: sqlite         # \"sqlite\" or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info             # trace | debug | info | warn | error\n  console:\n    enabled: true\n    level: info\n  file:\n    enabled: false\n    level: debug\n    dir: ./logs\n    filename: godex.log\n    max_size: 10485760    # 10MB\n    max_files: 5\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  max_queue_size: 10000\n  flush_interval_ms: 1000\n  batch_size: 100\n  capture_payload: false\n  payload_max_bytes: 65536\n```\n\n## Type Definitions\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class GodeXConfig {\n    +server: ServerConfig\n    +default_provider: string\n    +models: ModelsConfig\n    +providers: Record~string, ProviderConfig~\n    +session: SessionConfig\n    +logging: LoggingConfig\n    +trace: TraceConfig\n  }\n\n  class ServerConfig {\n    +port: number\n    +host: string\n    +idle_timeout: number\n  }\n\n  class ProviderConfig {\n    +spec: string\n    +credentials: CredentialsConfig\n    +endpoint: EndpointConfig\n    +timeout_ms: number\n  }\n\n  class CredentialsConfig {\n    +api_key: string\n  }\n\n  class EndpointConfig {\n    +base_url: string\n  }\n\n  class ModelsConfig {\n    +aliases: Record~string, string~\n  }\n\n  class SessionConfig {\n    +backend: string\n    +sqlite: SQLiteConfig\n  }\n\n  class LoggingConfig {\n    +level: LogLevel\n    +console: ConsoleLoggingConfig\n    +file: FileLoggingConfig\n  }\n\n  class TraceConfig {\n    +enabled: boolean\n    +path: string\n    +max_queue_size: number\n    +flush_interval_ms: number\n    +batch_size: number\n    +capture_payload: boolean\n    +payload_max_bytes: number\n  }\n\n  GodeXConfig --> ServerConfig\n  GodeXConfig --> ModelsConfig\n  GodeXConfig --> ProviderConfig\n  GodeXConfig --> SessionConfig\n  GodeXConfig --> LoggingConfig\n  GodeXConfig --> TraceConfig\n  ProviderConfig --> CredentialsConfig\n  ProviderConfig --> EndpointConfig\n```\n\n## Provider Config\n\nEach provider entry must include a `spec` field that matches a registered provider definition name. Legacy provider config without `spec` is rejected at startup.\n\n```yaml\nproviders:\n  myprovider:\n    spec: myprovider           # Required: matches registered definition\n    credentials:\n      api_key: ${MY_API_KEY}\n    endpoint:\n      base_url: https://api.example.com/v1\n    timeout_ms: 30000\n```\n\n## Environment Interpolation\n\nValues like `${DEEPSEEK_API_KEY}` are resolved at load time from environment variables. Missing variables produce a startup error.\n\n## Environment Variable Overrides\n\nBESIDES YAML interpolation, these environment variables directly override config fields at load time (CLI flags take precedence over both):\n\n| Variable | Config Field | Notes |\n|----------|-------------|-------|\n| `GODEX_PORT` | `server.port` | Overrides the listen port |\n| `GODEX_HOST` | `server.host` | Overrides the bind address |\n| `GODEX_LOG_LEVEL` | `logging.level` | Overrides the log level |\n| `GODEX_DEFAULT_PROVIDER` | `default_provider` | Falls back to `deepseek` if both are unset |\n\n[CLI Commands](/07-configuration/cli-commands)\n"}, "7a896165151c1b7d2f8822f102bdda120500d8f3": {"t": 1785748567.4840298, "n": 4381, "h": "9cbce00df922cc9c", "c": "---\ntitle: \"Config Schema\"\ndescription: \"Complete reference for godex.yaml configuration options.\"\nkeywords: \"GodeX, config schema, godex.yaml, YAML, server, providers, session\"\n---\n\n# Config Schema\n\nGodeX is configured via a `godex.yaml` file, typically created by `godex init`. Environment variables are interpolated using `${VAR_NAME}` syntax.\n\n## Full Schema\n\n```yaml\nserver:\n  port: 5678              # HTTP listen port\n  host: \"0.0.0.0\"         # Listen address\n  idle_timeout: 30000     # Idle connection timeout (ms)\n                         # Default: 0 (disabled)\n\ndefault_provider: deepseek   # Provider used when model has no slash prefix\n\nmodels:\n  aliases:\n    \"gpt-5.5\": deepseek/deepseek-v4-pro   # Maps alias to provider/model\n    \"glm\": zhipu/glm-5.1                   # Maps alias to provider/model\n    \"*\": deepseek/deepseek-v4-flash        # Catch-all fallback\n\nproviders:\n  deepseek:\n    spec: deepseek                      # Provider spec name (required)\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n    timeout_ms: 30000\n\n  zhipu:\n    spec: zhipu                         # Provider spec name (required)\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    timeout_ms: 30000\n\nsession:\n  backend: sqlite         # \"sqlite\" or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info             # trace | debug | info | warn | error\n  console:\n    enabled: true\n    level: info\n  file:\n    enabled: false\n    level: debug\n    dir: ./logs\n    filename: godex.log\n    max_size: 10485760    # 10MB\n    max_files: 5\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  max_queue_size: 10000\n  flush_interval_ms: 1000\n  batch_size: 100\n  capture_payload: false\n  payload_max_bytes: 65536\n```\n\n## Type Definitions\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class GodeXConfig {\n    +server: ServerConfig\n    +default_provider: string\n    +models: ModelsConfig\n    +providers: Record~string, ProviderConfig~\n    +session: SessionConfig\n    +logging: LoggingConfig\n    +trace: TraceConfig\n  }\n\n  class ServerConfig {\n    +port: number\n    +host: string\n    +idle_timeout: number\n  }\n\n  class ProviderConfig {\n    +spec: string\n    +credentials: CredentialsConfig\n    +endpoint: EndpointConfig\n    +timeout_ms: number\n  }\n\n  class CredentialsConfig {\n    +api_key: string\n  }\n\n  class EndpointConfig {\n    +base_url: string\n  }\n\n  class ModelsConfig {\n    +aliases: Record~string, string~\n  }\n\n  class SessionConfig {\n    +backend: string\n    +sqlite: SQLiteConfig\n  }\n\n  class LoggingConfig {\n    +level: LogLevel\n    +console: ConsoleLoggingConfig\n    +file: FileLoggingConfig\n  }\n\n  class TraceConfig {\n    +enabled: boolean\n    +path: string\n    +max_queue_size: number\n    +flush_interval_ms: number\n    +batch_size: number\n    +capture_payload: boolean\n    +payload_max_bytes: number\n  }\n\n  GodeXConfig --> ServerConfig\n  GodeXConfig --> ModelsConfig\n  GodeXConfig --> ProviderConfig\n  GodeXConfig --> SessionConfig\n  GodeXConfig --> LoggingConfig\n  GodeXConfig --> TraceConfig\n  ProviderConfig --> CredentialsConfig\n  ProviderConfig --> EndpointConfig\n```\n\n## Provider Config\n\nEach provider entry must include a `spec` field that matches a registered provider definition name. Legacy provider config without `spec` is rejected at startup.\n\n```yaml\nproviders:\n  myprovider:\n    spec: myprovider           # Required: matches registered definition\n    credentials:\n      api_key: ${MY_API_KEY}\n    endpoint:\n      base_url: https://api.example.com/v1\n    timeout_ms: 30000\n```\n\n## Environment Interpolation\n\nValues like `${DEEPSEEK_API_KEY}` are resolved at load time from environment variables. Missing variables produce a startup error.\n\n## Environment Variable Overrides\n\nBESIDES YAML interpolation, these environment variables directly override config fields at load time (CLI flags take precedence over both):\n\n| Variable | Config Field | Notes |\n|----------|-------------|-------|\n| `GODEX_PORT` | `server.port` | Overrides the listen port |\n| `GODEX_HOST` | `server.host` | Overrides the bind address |\n| `GODEX_LOG_LEVEL` | `logging.level` | Overrides the log level |\n| `GODEX_DEFAULT_PROVIDER` | `default_provider` | Falls back to `zhipu` if both are unset |\n\n[CLI Commands](/07-configuration/cli-commands)\n"}, "11869bda14585d5a812d6e629ea86a668edfdf47": {"t": 1785748568.569239, "n": 3802, "h": "758f54bba3c1d0cb", "c": "---\ntitle: \"Config Schema\"\ndescription: \"Complete reference for godex.yaml configuration options.\"\nkeywords: \"GodeX, config schema, godex.yaml, YAML, server, providers, session\"\n---\n\n# Config Schema\n\nGodeX is configured via a `godex.yaml` file, typically created by `godex init`. Environment variables are interpolated using `${VAR_NAME}` syntax.\n\n## Full Schema\n\n```yaml\nserver:\n  port: 5678              # HTTP listen port\n  host: \"0.0.0.0\"         # Listen address\n  idle_timeout: 30000     # Idle connection timeout (ms)\n\ndefault_provider: deepseek   # Provider used when model has no slash prefix\n\nmodels:\n  aliases:\n    \"gpt-5.5\": deepseek/deepseek-v4-pro   # Maps alias to provider/model\n    \"glm\": zhipu/glm-5.1                   # Maps alias to provider/model\n    \"*\": deepseek/deepseek-v4-flash        # Catch-all fallback\n\nproviders:\n  deepseek:\n    spec: deepseek                      # Provider spec name (required)\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n    timeout_ms: 30000\n\n  zhipu:\n    spec: zhipu                         # Provider spec name (required)\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    timeout_ms: 30000\n\nsession:\n  backend: sqlite         # \"sqlite\" or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info             # trace | debug | info | warn | error\n  console:\n    enabled: true\n    level: info\n  file:\n    enabled: false\n    level: debug\n    dir: ./logs\n    filename: godex.log\n    max_size: 10485760    # 10MB\n    max_files: 5\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  max_queue_size: 1000\n  flush_interval_ms: 1000\n  batch_size: 50\n  capture_payload: false\n  payload_max_bytes: 102400\n```\n\n## Type Definitions\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class GodeXConfig {\n    +server: ServerConfig\n    +default_provider: string\n    +models: ModelsConfig\n    +providers: Record~string, ProviderConfig~\n    +session: SessionConfig\n    +logging: LoggingConfig\n    +trace: TraceConfig\n  }\n\n  class ServerConfig {\n    +port: number\n    +host: string\n    +idle_timeout: number\n  }\n\n  class ProviderConfig {\n    +spec: string\n    +credentials: CredentialsConfig\n    +endpoint: EndpointConfig\n    +timeout_ms: number\n  }\n\n  class CredentialsConfig {\n    +api_key: string\n  }\n\n  class EndpointConfig {\n    +base_url: string\n  }\n\n  class ModelsConfig {\n    +aliases: Record~string, string~\n  }\n\n  class SessionConfig {\n    +backend: string\n    +sqlite: SQLiteConfig\n  }\n\n  class LoggingConfig {\n    +level: LogLevel\n    +console: ConsoleLoggingConfig\n    +file: FileLoggingConfig\n  }\n\n  class TraceConfig {\n    +enabled: boolean\n    +path: string\n    +max_queue_size: number\n    +flush_interval_ms: number\n    +batch_size: number\n    +capture_payload: boolean\n    +payload_max_bytes: number\n  }\n\n  GodeXConfig --> ServerConfig\n  GodeXConfig --> ModelsConfig\n  GodeXConfig --> ProviderConfig\n  GodeXConfig --> SessionConfig\n  GodeXConfig --> LoggingConfig\n  GodeXConfig --> TraceConfig\n  ProviderConfig --> CredentialsConfig\n  ProviderConfig --> EndpointConfig\n```\n\n## Provider Config\n\nEach provider entry must include a `spec` field that matches a registered provider definition name. Legacy provider config without `spec` is rejected at startup.\n\n```yaml\nproviders:\n  myprovider:\n    spec: myprovider           # Required: matches registered definition\n    credentials:\n      api_key: ${MY_API_KEY}\n    endpoint:\n      base_url: https://api.example.com/v1\n    timeout_ms: 30000\n```\n\n## Environment Interpolation\n\nValues like `${DEEPSEEK_API_KEY}` are resolved at load time from environment variables. Missing variables produce a startup error.\n\n[CLI Commands](/07-configuration/cli-commands)\n"}, "49620042afbb8aa691fe404cad0446fe9c08b7f7": {"t": 1785748569.6518888, "n": 2260, "h": "83d486dee5ba995d", "c": "---\ntitle: \"Config Schema\"\ndescription: \"Complete reference for godex.yaml configuration options.\"\nkeywords: \"GodeX, config schema, godex.yaml, YAML, server, providers, session\"\n---\n\n# Config Schema\n\nGodeX is configured via a `godex.yaml` file, typically created by `godex init`. Environment variables are interpolated using `${VAR_NAME}` syntax.\n\n## Full Schema\n\n```yaml\nserver:\n  port: 5678              # HTTP listen port\n  host: \"0.0.0.0\"         # Listen address\n  idle_timeout: 30000     # Idle connection timeout (ms)\n\ndefault_provider: zhipu   # Provider used when model has no slash prefix\n\nmodels:\n  aliases:\n    \"gpt-4o\": zhipu/glm-4.7   # Maps gpt-4o to provider-native glm-4.7\n    \"*\": zhipu/glm-5.1         # Catch-all fallback\n\nproviders:\n  zhipu:\n    api_key: ${ZHIPU_API_KEY}\n    base_url: https://open.bigmodel.cn/api/coding/paas/v4\n\nsession:\n  backend: sqlite         # \"sqlite\" or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info             # trace | debug | info | warn | error\n  console:\n    enabled: true\n    level: info\n  file:\n    enabled: false\n    level: debug\n    dir: ./logs\n    filename: godex.log\n    max_size: 10485760    # 10MB\n    max_files: 5\n```\n\n## Type Definitions\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class GodeXConfig {\n    +server: ServerConfig\n    +default_provider: string\n    +models: ModelsConfig\n    +providers: Record~string, ProviderConfig~\n    +session: SessionConfig\n    +logging: LoggingConfig\n  }\n\n  class ServerConfig {\n    +port: number\n    +host: string\n    +idle_timeout: number\n  }\n\n  class ProviderConfig {\n    +api_key: string\n    +base_url: string\n  }\n\n  class ModelsConfig {\n    +aliases: Record~string, string~\n  }\n\n  class SessionConfig {\n    +backend: string\n    +sqlite: SQLiteConfig\n  }\n\n  class LoggingConfig {\n    +level: LogLevel\n    +console: ConsoleLoggingConfig\n    +file: FileLoggingConfig\n  }\n\n  GodeXConfig --> ServerConfig\n  GodeXConfig --> ModelsConfig\n  GodeXConfig --> ProviderConfig\n  GodeXConfig --> SessionConfig\n  GodeXConfig --> LoggingConfig\n```\n\n## Environment Interpolation\n\nValues like `${ZHIPU_API_KEY}` are resolved at load time from `process.env`. Missing variables produce a startup error.\n\n[CLI Commands](/07-configuration/cli-commands)\n"}, "65ab216ae876c7c09e193f4d7266a36f639aa92c": {"t": 1785748570.787158, "n": 2198, "h": "c9dd1970fe82be9c", "c": "---\ntitle: \"Config Schema\"\ndescription: \"Complete reference for godex.yaml configuration options.\"\nkeywords: \"GodeX, config schema, godex.yaml, YAML, server, providers, session\"\n---\n\n# Config Schema\n\nGodeX is configured via a `godex.yaml` file, typically created by `godex init`. Environment variables are interpolated using `${VAR_NAME}` syntax.\n\n## Full Schema\n\n```yaml\nserver:\n  port: 5678              # HTTP listen port\n  host: \"0.0.0.0\"         # Listen address\n  idle_timeout: 30000     # Idle connection timeout (ms)\n\ndefault_provider: zhipu   # Provider used when model has no slash prefix\n\nproviders:\n  zhipu:\n    api_key: ${ZHIPU_API_KEY}\n    base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    models:               # Model name mapping table\n      \"gpt-4o\": glm-4.7   # Maps gpt-4o to provider-native glm-4.7\n      \"*\": glm-5.1        # Catch-all fallback\n\nsession:\n  backend: sqlite         # \"sqlite\" or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info             # trace | debug | info | warn | error\n  console:\n    enabled: true\n    level: info\n  file:\n    enabled: false\n    level: debug\n    dir: ./logs\n    filename: godex.log\n    max_size: 10485760    # 10MB\n    max_files: 5\n```\n\n## Type Definitions\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class GodeXConfig {\n    +server: ServerConfig\n    +default_provider: string\n    +providers: Record~string, ProviderConfig~\n    +session: SessionConfig\n    +logging: LoggingConfig\n  }\n\n  class ServerConfig {\n    +port: number\n    +host: string\n    +idle_timeout: number\n  }\n\n  class ProviderConfig {\n    +api_key: string\n    +base_url: string\n    +models: Record~string, string~\n  }\n\n  class SessionConfig {\n    +backend: string\n    +sqlite: SQLiteConfig\n  }\n\n  class LoggingConfig {\n    +level: LogLevel\n    +console: ConsoleLoggingConfig\n    +file: FileLoggingConfig\n  }\n\n  GodeXConfig --> ServerConfig\n  GodeXConfig --> ProviderConfig\n  GodeXConfig --> SessionConfig\n  GodeXConfig --> LoggingConfig\n```\n\n## Environment Interpolation\n\nValues like `${ZHIPU_API_KEY}` are resolved at load time from `process.env`. Missing variables produce a startup error.\n\n[CLI Commands](/07-configuration/cli-commands)\n"}, "29cb3a87490dc075b5d879b8e171099c84e8981f": {"t": 1785748571.9047074, "n": 2119, "h": "3f4309fcb9fa51b3", "c": "---\ntitle: \"Config Schema\"\ndescription: \"Complete reference for godex.yaml configuration options.\"\n---\n\n# Config Schema\n\nGodeX is configured via a `godex.yaml` file, typically created by `godex init`. Environment variables are interpolated using `${VAR_NAME}` syntax.\n\n## Full Schema\n\n```yaml\nserver:\n  port: 5678              # HTTP listen port\n  host: \"0.0.0.0\"         # Listen address\n  idle_timeout: 30000     # Idle connection timeout (ms)\n\ndefault_provider: zhipu   # Provider used when model has no slash prefix\n\nproviders:\n  zhipu:\n    api_key: ${ZHIPU_API_KEY}\n    base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    models:               # Model name mapping table\n      \"gpt-4o\": glm-4.7   # Maps gpt-4o to provider-native glm-4.7\n      \"*\": glm-5.1        # Catch-all fallback\n\nsession:\n  backend: sqlite         # \"sqlite\" or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info             # trace | debug | info | warn | error\n  console:\n    enabled: true\n    level: info\n  file:\n    enabled: false\n    level: debug\n    dir: ./logs\n    filename: godex.log\n    max_size: 10485760    # 10MB\n    max_files: 5\n```\n\n## Type Definitions\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class GodeXConfig {\n    +server: ServerConfig\n    +default_provider: string\n    +providers: Record~string, ProviderConfig~\n    +session: SessionConfig\n    +logging: LoggingConfig\n  }\n\n  class ServerConfig {\n    +port: number\n    +host: string\n    +idle_timeout: number\n  }\n\n  class ProviderConfig {\n    +api_key: string\n    +base_url: string\n    +models: Record~string, string~\n  }\n\n  class SessionConfig {\n    +backend: string\n    +sqlite: SQLiteConfig\n  }\n\n  class LoggingConfig {\n    +level: LogLevel\n    +console: ConsoleLoggingConfig\n    +file: FileLoggingConfig\n  }\n\n  GodeXConfig --> ServerConfig\n  GodeXConfig --> ProviderConfig\n  GodeXConfig --> SessionConfig\n  GodeXConfig --> LoggingConfig\n```\n\n## Environment Interpolation\n\nValues like `${ZHIPU_API_KEY}` are resolved at load time from `process.env`. Missing variables produce a startup error.\n\n[CLI Commands](/07-configuration/cli-commands)\n"}, "f6b3168d68a00be5ba80b0d259ab8d648d4e9691": {"t": 1785748573.0048952, "n": 2119, "h": "769ef1cb9b2b4c23", "c": "---\ntitle: \"Config Schema\"\ndescription: \"Complete reference for godex.yaml configuration options.\"\n---\n\n# Config Schema\n\nGodex is configured via a `godex.yaml` file, typically created by `godex init`. Environment variables are interpolated using `${VAR_NAME}` syntax.\n\n## Full Schema\n\n```yaml\nserver:\n  port: 5678              # HTTP listen port\n  host: \"0.0.0.0\"         # Listen address\n  idle_timeout: 30000     # Idle connection timeout (ms)\n\ndefault_provider: zhipu   # Provider used when model has no slash prefix\n\nproviders:\n  zhipu:\n    api_key: ${ZHIPU_API_KEY}\n    base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    models:               # Model name mapping table\n      \"gpt-4o\": glm-4.7   # Maps gpt-4o to provider-native glm-4.7\n      \"*\": glm-5.1        # Catch-all fallback\n\nsession:\n  backend: sqlite         # \"sqlite\" or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info             # trace | debug | info | warn | error\n  console:\n    enabled: true\n    level: info\n  file:\n    enabled: false\n    level: debug\n    dir: ./logs\n    filename: godex.log\n    max_size: 10485760    # 10MB\n    max_files: 5\n```\n\n## Type Definitions\n\n```mermaid\nclassDiagram\n  direction TB\n\n  class GodexConfig {\n    +server: ServerConfig\n    +default_provider: string\n    +providers: Record~string, ProviderConfig~\n    +session: SessionConfig\n    +logging: LoggingConfig\n  }\n\n  class ServerConfig {\n    +port: number\n    +host: string\n    +idle_timeout: number\n  }\n\n  class ProviderConfig {\n    +api_key: string\n    +base_url: string\n    +models: Record~string, string~\n  }\n\n  class SessionConfig {\n    +backend: string\n    +sqlite: SQLiteConfig\n  }\n\n  class LoggingConfig {\n    +level: LogLevel\n    +console: ConsoleLoggingConfig\n    +file: FileLoggingConfig\n  }\n\n  GodexConfig --> ServerConfig\n  GodexConfig --> ProviderConfig\n  GodexConfig --> SessionConfig\n  GodexConfig --> LoggingConfig\n```\n\n## Environment Interpolation\n\nValues like `${ZHIPU_API_KEY}` are resolved at load time from `process.env`. Missing variables produce a startup error.\n\n[CLI Commands](/07-configuration/cli-commands)\n"}, "9efb5d28b803166fc52e46da8d469512befd054b": {"t": 1786067854.4240422, "n": 10744, "h": "f36cdc59376ddb81", "c": "---\ntitle: \"Config Schema\"\ndescription: \"Complete reference for godex.yaml configuration options.\"\nkeywords: \"GodeX, config schema, godex.yaml, YAML, server, providers, session\"\n---\n\n# Config Schema\n\nGodeX is configured via a `godex.yaml` file, typically created by `godex init`. Environment variables are interpolated using `${VAR_NAME}` syntax.\n\n## Full Schema\n\n```yaml\nserver:\n  port: 5678              # HTTP listen port\n  host: \"0.0.0.0\"         # Listen address\n  idle_timeout: 30000     # Idle connection timeout (ms)\n                         # Default: 0 (disabled)\n\ndefault_provider: deepseek   # Provider used when model has no slash prefix\n\nmodels:\n  aliases:\n    \"gpt-5.5\": deepseek/deepseek-v4-pro   # Maps alias to provider/model\n    \"glm\": zhipu/glm-5.1                   # Maps alias to provider/model\n    \"*\": deepseek/deepseek-v4-flash        # Catch-all fallback\n\nproviders:\n  deepseek:\n    spec: deepseek                      # Provider spec name (required)\n    credentials:\n      api_key: ${DEEPSEEK_API_KEY}\n    endpoint:\n      base_url: https://api.deepseek.com\n    timeout_ms: 30000\n\n  zhipu:\n    spec: zhipu                         # Provider spec name (required)\n    credentials:\n      api_key: ${ZHIPU_API_KEY}\n    endpoint:\n      base_url: https://open.bigmodel.cn/api/coding/paas/v4\n    timeout_ms: 30000\n\n  minimax:\n    spec: minimax                        # Provider spec name (required)\n    credentials:\n      api_key: ${MINIMAX_API_KEY}\n    endpoint:\n      base_url: https://api.minimaxi.com/v1\n    timeout_ms: 30000\n\nsession:\n  backend: sqlite         # \"sqlite\" or \"memory\"\n  sqlite:\n    path: ./data/sessions.db\n\nlogging:\n  level: info             # trace | debug | info | warn | error\n  console:\n    enabled: true\n    level: info\n  file:\n    enabled: false\n    level: debug\n    dir: ./logs\n    filename: godex.log\n    max_size: 10485760    # 10MB\n    max_files: 5\n\nweb_search:                      # Built-in web search (default: enabled, no provider)\n  enabled: true                  # Master switch\n  mode: auto                     # auto | provider_native | godex_managed | disabled\n  provider: none                 # none | mock | zhipu (search backend for godex_managed)\n  on_unavailable: client_tool_call  # client_tool_call | fail | ignore\n  max_iterations: 2              # Max managed search rounds per request\n  timeout_ms: 10000              # Per-search timeout\n\ntrace:\n  enabled: true\n  path: ./data/trace.db\n  max_queue_size: 10000\n  flush_interval_ms: 1000\n  batch_size: 100\n  capture_payload: false\n  payload_max_bytes: 65536\n```\n\n## Type Definitions\n\n```mermaid\nclassDiagram\n\n  class GodeXConfig {\n    +server: ServerConfig\n    +default_provider: string\n    +models: ModelsConfig\n    +providers: Record~string, ProviderConfig~\n    +session: SessionConfig\n    +logging: LoggingConfig\n    +web_search: WebSearchConfig\n    +trace: TraceConfig\n  }\n\n  class ServerConfig {\n    +port: number\n    +host: string\n    +idle_timeout: number\n  }\n\n  class ProviderConfig {\n    +spec: string\n    +credentials: CredentialsConfig\n    +endpoint: EndpointConfig\n    +timeout_ms: number\n  }\n\n  class CredentialsConfig {\n    +api_key: string\n  }\n\n  class EndpointConfig {\n    +base_url: string\n  }\n\n  class ModelsConfig {\n    +aliases: Record~string, string~\n  }\n\n  class SessionConfig {\n    +backend: string\n    +sqlite: SQLiteConfig\n  }\n\n  class LoggingConfig {\n    +level: LogLevel\n    +console: ConsoleLoggingConfig\n    +file: FileLoggingConfig\n  }\n\n  class TraceConfig {\n    +enabled: boolean\n    +path: string\n    +max_queue_size: number\n    +flush_interval_ms: number\n    +batch_size: number\n    +capture_payload: boolean\n    +payload_max_bytes: number\n  }\n\n  class WebSearchConfig {\n    +enabled: boolean\n    +mode: WebSearchMode\n    +provider: WebSearchProvider\n    +on_unavailable: WebSearchOnUnavailable\n    +max_iterations: number\n    +timeout_ms: number\n  }\n\n  GodeXConfig --> ServerConfig\n  GodeXConfig --> ModelsConfig\n  GodeXConfig --> ProviderConfig\n  GodeXConfig --> SessionConfig\n  GodeXConfig --> LoggingConfig\n  GodeXConfig --> WebSearchConfig\n  GodeXConfig --> TraceConfig\n  ProviderConfig --> CredentialsConfig\n  ProviderConfig --> EndpointConfig\n```\n\n## Provider Config\n\nEach provider entry must include a `spec` field that matches a registered provider definition name. Legacy provider config without `spec` is rejected at startup.\n\n```yaml\nproviders:\n  myprovider:\n    spec: myprovider           # Required: matches registered definition\n    credentials:\n      api_key: ${MY_API_KEY}\n    endpoint:\n      base_url: https://api.example.com/v1\n    timeout_ms: 30000\n```\n\n## Web Search\n\nGodeX can run web search in two ways: let the provider handle it natively, or run the search itself (\"GodeX-managed\" / \"hosted\") and feed results back into a continuation request. The `web_search` block ([src/config/sections/web-search.ts:10](https://github.com/Ahoo-Wang/GodeX/blob/main/src/config/sections/web-search.ts#L10)) controls this.\n\n::: warning Important: native providers always use native search\nFor providers whose tool set already includes `web_search` as a native tool (Zhipu, Xiaomi), the planner returns the tool as natively supported **before** consulting `mode`. This means `mode: godex_managed` and `mode: disabled` have **no effect** on those providers — they always get native `web_search`. The `mode` settings below govern how `web_search` is handled for providers that do **not** support it natively (DeepSeek, MiniMax), or when you want GodeX to host the search loop. See [tool-plan.ts:129](https://github.com/Ahoo-Wang/GodeX/blob/main/src/bridge/tools/tool-plan.ts#L129) for the precedence (native → degraded → web-search planning).\n:::\n\n| Field | Default | Description |\n|-------|---------|-------------|\n| `enabled` | `true` | Master switch. When `false`, the effective `mode` becomes `disabled` and `available` is `false`. |\n| `mode` | `auto` | Execution strategy — see the table below (applies to non-native providers). |\n| `provider` | `none` | The search backend GodeX uses in `godex_managed` mode. |\n| `on_unavailable` | `client_tool_call` | What to do when managed search is selected but no backend is available. |\n| `max_iterations` | `2` | Maximum number of managed search rounds per request. |\n| `timeout_ms` | `10000` | Per-search timeout in milliseconds. |\n\n### `mode` — execution strategy\n\nThese modes apply to providers that do **not** support `web_search` natively. The planner ([tool-plan.ts:164](https://github.com/Ahoo-Wang/GodeX/blob/main/src/bridge/tools/tool-plan.ts#L164)) reaches web-search planning only after the native and degraded checks, so for native providers the tool is always handled by the provider regardless of `mode`.\n\n| Mode | Behavior (non-native providers) |\n|------|----------|\n| `auto` | If a search `provider` backend is `available`, GodeX hosts the search loop (managed); otherwise the `on_unavailable` policy applies. |\n| `provider_native` | Declares the tool with provider-native execution. For providers without native `web_search`, this falls through to web-search planning like `auto`. |\n| `godex_managed` | GodeX intercepts the `web_search` function call, runs the search itself via the configured `provider` backend, emits the `web_search_call` lifecycle (`in_progress` → `searching` → `completed` / failed), and submits a continuation request with the results. Up to `max_iterations` rounds. If no backend is `available`, the `on_unavailable` policy applies. |\n| `disabled` | The managed loop is not offered. For non-native providers the `on_unavailable` policy still applies (default `client_tool_call`), so a search tool may still be exposed as a client-visible function call — set `on_unavailable: ignore` (or `fail`) to suppress it entirely. |\n\n### `provider` — managed search backend\n\n| Provider | Description |\n|----------|-------------|\n| `none` | No backend. Managed search is unavailable (`available` is `false`); the `on_unavailable` policy then applies. |\n| `mock` | Returns canned results; used for testing. |\n| `zhipu` | [Zhipu Web Search API](https://open.bigmodel.cn/dev/api/search-tool/websearch). |\n\n::: warning The Zhipu search backend reads the provider config, not just env\nSelecting `provider: zhipu` makes the backend `available` only when a `providers.zhipu` block with a `credentials.api_key` exists in `godex.yaml` — `createSearchService` reads `config.providers.zhipu.credentials.api_key` ([search/registry.ts:16-17](https://github.com/Ahoo-Wang/GodeX/blob/main/src/search/registry.ts#L16-L17)) and falls back to a no-op provider when it is absent. So on a DeepSeek/MiniMax-only config, exporting `ZHIPU_API_KEY` alone is **not** enough; add a full `providers.zhipu` entry (env interpolation works, e.g. `api_key: ${ZHIPU_API_KEY}`), or GodeX will take the `on_unavailable` path instead of hosting search.\n:::\n\n### `on_unavailable` — fallback policy\n\nApplies when the managed search loop is selected (`mode` is `auto`/`godex_managed`) but no backend is `available`, as well as when `mode` is `disabled` for a non-native provider.\n\n| Policy | Behavior |\n|--------|----------|\n| `client_tool_call` | Forward the `web_search` call to the client as a normal function call (the client handles it). |\n| `fail` | Fail the request with a `BridgeError`. |\n| `ignore` | Silently drop the search call. |\n\n::: tip\nWith the shipped defaults (`mode: auto`, `provider: none`), providers that support native web search (Zhipu, Xiaomi) use it directly, while other providers forward `web_search` calls to the client. To enable GodeX-managed search for **non-native** providers, set `provider: zhipu` **and** add a `providers.zhipu` block (with `credentials.api_key`) to `godex.yaml` — see the warning above.\n:::\n\nThe managed search loop is implemented by `HostedWebSearchStreamRunner` / `HostedWebSearchSyncRunner` in `src/responses/web-search/`. See [Streaming Pipeline](../02-architecture/streaming-pipeline.md) for how it integrates into the event production stage.\n\n## Environment Interpolation\n\nValues like `${DEEPSEEK_API_KEY}` are resolved at load time from environment variables. Missing variables produce a startup error.\n\n## Environment Variable Overrides\n\nBESIDES YAML interpolation, these environment variables directly override config fields at load time (CLI flags take precedence over both):\n\n| Variable | Config Field | Notes |\n|----------|-------------|-------|\n| `GODEX_PORT` | `server.port` | Overrides the listen port |\n| `GODEX_HOST` | `server.host` | Overrides the bind address |\n| `GODEX_LOG_LEVEL` | `logging.level` | Overrides the log level |\n| `GODEX_DEFAULT_PROVIDER` | `default_provider` | Falls back to `deepseek` if both are unset |\n\n[CLI Commands](/07-configuration/cli-commands)\n\n"}}, "wiki/03-provider-development/deepseek-reference.md": {"e4b02fa899c22db59bd7a257edccad7d2aae168d": {"t": 1786068485.467974, "n": 5061, "h": "63c1a089f9b59210", "c": "---\ntitle: \"DeepSeek Reference Implementation\"\ndescription: \"Walkthrough of the DeepSeek provider — demonstrating native reasoning effort, cached token usage, and content array handling.\"\nkeywords: \"GodeX, DeepSeek, provider reference, implementation\"\n---\n\n# DeepSeek Reference Implementation\n\nThe DeepSeek provider is one of the bundled reference implementations in GodeX. It demonstrates native reasoning effort support, cached token usage reporting, and defensive content array text extraction.\n\n## Module Structure\n\n```\nsrc/providers/deepseek/\n├── spec.ts         # DEEPSEEK_PROVIDER_SPEC declaration with capabilities and accessors\n├── client.ts       # createDeepSeekProviderEdge() factory\n├── hooks.ts        # Provider-specific hooks (patchRequest, usage mapping, deltas)\n├── protocol/       # DeepSeek-specific type definitions\n│   ├── completions.ts  # Request/response DTOs including thinking types\n│   └── index.ts        # Barrel exports\n└── index.ts        # Public exports\n```\n\n## Spec Declaration\n\nThe `DEEPSEEK_PROVIDER_SPEC` in `spec.ts` declares all capabilities, accessors, and hooks:\n\n```ts\nexport const DEEPSEEK_PROVIDER_SPEC: ProviderSpec<\n  BridgeChatCompletionCreateRequest,\n  ChatCompletion,\n  ChatCompletionChunk,\n  ChatCompletionRequest\n> = {\n  name: DEEPSEEK_PROVIDER_NAME,\n  protocol: CHAT_COMPLETIONS_PROTOCOL,\n  capabilities: DEEPSEEK_SPEC_CAPABILITIES,\n  endpoint: { defaultBaseURL: DEFAULT_DEEPSEEK_BASE_URL },\n  auth: BEARER_AUTH,\n  toolName: DEFAULT_TOOL_NAME_CODEC,\n  response: {\n    firstChoice: deepSeekFirstChoice,\n    finishReason: deepSeekFinishReason,\n    outputText: deepSeekOutputText,\n    usage: deepSeekResponseUsage,\n  },\n  stream: { deltas: deepSeekStreamDeltas },\n  hooks: { patchRequest: deepSeekPatchRequest },\n};\n```\n\n## Capabilities\n\n```ts\nconst DEEPSEEK_SPEC_CAPABILITIES: ProviderCapabilities = {\n  parameters: {\n    supported: new Set([\n      \"stream\", \"temperature\", \"top_p\", \"max_output_tokens\",\n      \"safety_identifier\", \"user\", \"reasoning\", \"text.format\",\n    ]),\n  },\n  tools: {\n    supported: new Set([\n      \"function\", \"local_shell\", \"shell\", \"apply_patch\",\n      \"custom\", \"namespace\",\n    ]),\n    degraded: new Map([\n      [\"local_shell\", \"function\"],\n      [\"shell\", \"function\"],\n      [\"apply_patch\", \"function\"],\n      [\"custom\", \"function\"],\n      [\"namespace\", \"function\"],\n    ]),\n    maxTools: 128,\n  },\n  toolChoice: { supported: new Set([\"auto\", \"none\", \"required\", \"function\"]) },\n  responseFormats: { supported: new Set([\"text\", \"json_object\"]) },\n  reasoning: { effort: \"native\" },\n  streaming: { usage: true },\n};\n```\n\nNotable capability details:\n\n- **Native reasoning effort**: DeepSeek supports `reasoning.effort: \"native\"`, meaning the bridge maps Responses API effort values to DeepSeek's native `reasoning_effort` parameter.\n- **Tool degradation**: Codex built-in tools (`local_shell`, `shell`, `apply_patch`, `custom`, `namespace`) are degraded to `function` type.\n- **Max 128 tools**: DeepSeek accepts up to 128 tools per request.\n- **Cached tokens**: DeepSeek reports `prompt_cache_hit_tokens` which are mapped to `input_tokens_details.cached_tokens`.\n\n## Hooks\n\n### `deepSeekPatchRequest`\n\nTransforms the bridge's Chat Completions request for DeepSeek-specific behavior:\n\n1. Maps `reasoning_effort` values: `high` → `high`, `xhigh` → `max`.\n2. Sets `thinking: { type: \"enabled\" }` when reasoning is active or when historical messages contain `reasoning_content`.\n3. Sets `thinking: { type: \"disabled\" }` when no reasoning is needed.\n\n### `deepSeekStreamDeltas`\n\nExtracts typed deltas from DeepSeek's SSE chunks:\n\n- `content` → text delta\n- `reasoning_content` → reasoning delta\n- `tool_calls` → tool call deltas (via shared `mapCommonChatStreamDelta`)\n- `usage` → usage delta (with cached token mapping)\n- `finish_reason` → finish reason delta\n\n### `mapDeepSeekSpecUsage`\n\nMaps DeepSeek's usage format to the standard `ResponseUsage` type, including:\n\n- `prompt_cache_hit_tokens` → `input_tokens_details.cached_tokens`\n- `completion_tokens_details.reasoning_tokens` → `output_tokens_details.reasoning_tokens`\n\n## Client Construction\n\nThe `createDeepSeekProviderEdge()` function in `client.ts` builds the `ProviderEdge`:\n\n1. Creates a `ChatProviderClient` with the provider's base URL, API key, and timeout.\n2. Uses `createProviderEdge()` from the bridge kernel to wrap the spec, config, and HTTP methods.\n\n## Registration\n\nThe provider is registered in `src/providers/builtin.ts`:\n\n```ts\nexport const DEEPSEEK_PROVIDER_DEFINITION = createProviderDefinition(\n  DEEPSEEK_PROVIDER_NAME,\n  createDeepSeekProviderEdge,\n);\n```\n\nThe default DeepSeek base URL is `https://api.deepseek.com`. The default model is `deepseek-v4-pro`.\n\n## Content Handling\n\nDeepSeek may return `message.content` as either a string or an array of content parts. The `deepSeekOutputText` accessor handles both cases, extracting text from `type: \"text\"` parts in array content.\n\n[MiniMax Reference](/03-provider-development/minimax-reference)\n[Zhipu Reference](/03-provider-development/zhipu-reference)\n"}}}}