coding-proxy 0.5.2a8__tar.gz → 0.6.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (236) hide show
  1. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/.gitignore +3 -0
  2. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/CHANGELOG.md +24 -1
  3. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/PKG-INFO +15 -8
  4. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/README.md +12 -6
  5. coding_proxy-0.6.0/assets/dashboard/config-tab.png +0 -0
  6. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/.agents/issue.md +119 -8
  7. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/.agents/knowledge-map.md +11 -21
  8. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/arch/config-reference.md +66 -37
  9. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/arch/design-patterns.md +1 -1
  10. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/arch/testing.md +18 -5
  11. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/arch/vendors.md +1 -1
  12. coding_proxy-0.6.0/docs/diagrams/config-resolution-storage/config-resolution-storage.html +13927 -0
  13. coding_proxy-0.6.0/docs/diagrams/config-resolution-storage/config-resolution-storage.json +94 -0
  14. coding_proxy-0.6.0/docs/diagrams/config-resolution-storage/config-resolution-storage.svg +764 -0
  15. coding_proxy-0.6.0/docs/diagrams/config-resolution-storage/config-resolution-storage.visual-check.json +930 -0
  16. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/framework.md +5 -5
  17. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/guide/api-reference.md +42 -8
  18. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/guide/cli-reference.md +94 -10
  19. coding_proxy-0.6.0/docs/guide/dashboard.md +88 -0
  20. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/guide/monitoring.md +3 -1
  21. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/guide/quickstart.md +17 -12
  22. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/guide/vendors.md +1 -1
  23. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/user-guide.md +45 -36
  24. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/zh-CN/README.md +12 -6
  25. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/pyproject.toml +2 -1
  26. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/auth/runtime.py +8 -0
  27. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/auth/store.py +4 -4
  28. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/cli/__init__.py +148 -44
  29. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/cli/auth_commands.py +47 -8
  30. coding_proxy-0.6.0/src/coding/proxy/cli/config_commands.py +232 -0
  31. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/config/auth_schema.py +6 -2
  32. coding_proxy-0.6.0/src/coding/proxy/config/config.default.yaml +737 -0
  33. coding_proxy-0.6.0/src/coding/proxy/config/defaults.py +34 -0
  34. coding_proxy-0.6.0/src/coding/proxy/config/home.py +188 -0
  35. coding_proxy-0.6.0/src/coding/proxy/config/importer.py +812 -0
  36. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/config/loader.py +16 -47
  37. coding_proxy-0.6.0/src/coding/proxy/config/normalize.py +300 -0
  38. coding_proxy-0.6.0/src/coding/proxy/config/resolver.py +412 -0
  39. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/config/routing.py +13 -4
  40. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/config/schema.py +8 -4
  41. coding_proxy-0.6.0/src/coding/proxy/config/secrets.py +286 -0
  42. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/config/server.py +8 -3
  43. coding_proxy-0.6.0/src/coding/proxy/config/service.py +1182 -0
  44. coding_proxy-0.6.0/src/coding/proxy/config/store.py +384 -0
  45. coding_proxy-0.6.0/src/coding/proxy/config/ui_registry.py +669 -0
  46. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/executor.py +19 -14
  47. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/quota_guard.py +31 -7
  48. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/server/app.py +27 -6
  49. coding_proxy-0.6.0/src/coding/proxy/server/config_routes.py +360 -0
  50. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/server/dashboard.py +270 -58
  51. coding_proxy-0.6.0/src/coding/proxy/server/generations.py +718 -0
  52. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/server/routes.py +21 -15
  53. coding_proxy-0.6.0/src/coding/proxy/server/security.py +350 -0
  54. coding_proxy-0.6.0/src/coding/proxy/server/static/config/config.css +181 -0
  55. coding_proxy-0.6.0/src/coding/proxy/server/static/config/config.js +1267 -0
  56. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/token_manager.py +2 -1
  57. coding_proxy-0.6.0/tests/conftest.py +146 -0
  58. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_app_routes.py +86 -3
  59. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_cli_usage.py +1 -1
  60. coding_proxy-0.6.0/tests/test_config_api.py +663 -0
  61. coding_proxy-0.6.0/tests/test_config_cli.py +342 -0
  62. coding_proxy-0.6.0/tests/test_config_import.py +559 -0
  63. coding_proxy-0.6.0/tests/test_config_init.py +96 -0
  64. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_config_loader.py +2 -0
  65. coding_proxy-0.6.0/tests/test_config_normalize.py +143 -0
  66. coding_proxy-0.6.0/tests/test_config_secrets.py +199 -0
  67. coding_proxy-0.6.0/tests/test_config_service.py +1047 -0
  68. coding_proxy-0.6.0/tests/test_config_store.py +319 -0
  69. coding_proxy-0.6.0/tests/test_config_ui_registry.py +68 -0
  70. coding_proxy-0.6.0/tests/test_dashboard_config_tab.py +810 -0
  71. coding_proxy-0.6.0/tests/test_generations.py +552 -0
  72. coding_proxy-0.6.0/tests/test_generations_app.py +457 -0
  73. coding_proxy-0.6.0/tests/test_generations_cli.py +158 -0
  74. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_quota_guard.py +68 -2
  75. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_router_executor.py +14 -2
  76. coding_proxy-0.6.0/tests/test_security_middleware.py +442 -0
  77. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_token_manager.py +7 -2
  78. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/uv.lock +161 -2
  79. coding_proxy-0.5.2a8/AGENTS.md +0 -58
  80. coding_proxy-0.5.2a8/CLAUDE.md +0 -1
  81. coding_proxy-0.5.2a8/docs/.agents/browser-validation.md +0 -172
  82. coding_proxy-0.5.2a8/docs/.agents/reference-specifications.md +0 -16
  83. coding_proxy-0.5.2a8/docs/guide/dashboard.md +0 -63
  84. coding_proxy-0.5.2a8/tests/test_config_init.py +0 -156
  85. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/.github/workflows/ci.yml +0 -0
  86. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/.github/workflows/coverage.yml +0 -0
  87. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/.github/workflows/release.yml +0 -0
  88. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/.pre-commit-config.yaml +0 -0
  89. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/LICENSE +0 -0
  90. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/assets/dashboard-v0.4.0.png +0 -0
  91. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/assets/logo.svg +0 -0
  92. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/assets/model-calling-v0.5.0.png +0 -0
  93. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/assets/session-v0.4.0.png +0 -0
  94. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/arch/convert.md +0 -0
  95. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/arch/routing.md +0 -0
  96. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/docs/ops/ci-cd.md +0 -0
  97. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/__init__.py +0 -0
  98. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/__init__.py +0 -0
  99. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/__main__.py +0 -0
  100. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/auth/__init__.py +0 -0
  101. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/auth/providers/__init__.py +0 -0
  102. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/auth/providers/base.py +0 -0
  103. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/auth/providers/github.py +0 -0
  104. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/auth/providers/google.py +0 -0
  105. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/cli/banner.py +0 -0
  106. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/compat/__init__.py +0 -0
  107. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/compat/canonical.py +0 -0
  108. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/compat/session_store.py +0 -0
  109. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/config/__init__.py +0 -0
  110. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/config/resiliency.py +0 -0
  111. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/config/session_policy.py +0 -0
  112. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/config/vendors.py +0 -0
  113. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/convert/__init__.py +0 -0
  114. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/convert/anthropic_to_gemini.py +0 -0
  115. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/convert/anthropic_to_openai.py +0 -0
  116. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/convert/gemini_sse_adapter.py +0 -0
  117. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/convert/gemini_to_anthropic.py +0 -0
  118. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/convert/openai_to_anthropic.py +0 -0
  119. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/convert/vendor_channels.py +0 -0
  120. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/logging/__init__.py +0 -0
  121. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/logging/db.py +0 -0
  122. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/logging/formatters.py +0 -0
  123. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/logging/stats.py +0 -0
  124. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/model/__init__.py +0 -0
  125. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/model/auth.py +0 -0
  126. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/model/compat.py +0 -0
  127. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/model/constants.py +0 -0
  128. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/model/pricing.py +0 -0
  129. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/model/token.py +0 -0
  130. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/model/vendor.py +0 -0
  131. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/native_api/__init__.py +0 -0
  132. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/native_api/config.py +0 -0
  133. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/native_api/extractors/__init__.py +0 -0
  134. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/native_api/extractors/anthropic.py +0 -0
  135. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/native_api/extractors/gemini.py +0 -0
  136. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/native_api/extractors/openai.py +0 -0
  137. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/native_api/handler.py +0 -0
  138. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/native_api/operation.py +0 -0
  139. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/native_api/routes.py +0 -0
  140. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/native_api/usage_registry.py +0 -0
  141. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/pricing.py +0 -0
  142. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/__init__.py +0 -0
  143. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/circuit_breaker.py +0 -0
  144. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/error_classifier.py +0 -0
  145. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/model_mapper.py +0 -0
  146. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/rate_limit.py +0 -0
  147. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/retry.py +0 -0
  148. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/router.py +0 -0
  149. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/session_manager.py +0 -0
  150. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/session_policy.py +0 -0
  151. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/tier.py +0 -0
  152. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/usage_parser.py +0 -0
  153. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/routing/usage_recorder.py +0 -0
  154. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/server/__init__.py +0 -0
  155. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/server/factory.py +0 -0
  156. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/server/responses.py +0 -0
  157. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/streaming/__init__.py +0 -0
  158. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/streaming/anthropic_compat.py +0 -0
  159. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/__init__.py +0 -0
  160. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/alibaba.py +0 -0
  161. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/anthropic.py +0 -0
  162. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/antigravity.py +0 -0
  163. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/base.py +0 -0
  164. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/concurrency.py +0 -0
  165. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/copilot.py +0 -0
  166. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/copilot_models.py +0 -0
  167. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/copilot_token_manager.py +0 -0
  168. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/copilot_urls.py +0 -0
  169. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/doubao.py +0 -0
  170. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/kimi.py +0 -0
  171. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/minimax.py +0 -0
  172. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/mixins.py +0 -0
  173. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/native_anthropic.py +0 -0
  174. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/xiaomi.py +0 -0
  175. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/src/coding/proxy/vendors/zhipu.py +0 -0
  176. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/__init__.py +0 -0
  177. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/e2e/__init__.py +0 -0
  178. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/e2e/conftest.py +0 -0
  179. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/e2e/test_e2e_http.py +0 -0
  180. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/e2e/test_e2e_token.py +0 -0
  181. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/e2e/test_e2e_vendor.py +0 -0
  182. /coding_proxy-0.5.2a8/src/coding/proxy/config/config.default.yaml → /coding_proxy-0.6.0/tests/fixtures/legacy_config_default_v052.yaml +0 -0
  183. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_antigravity.py +0 -0
  184. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_auto_login.py +0 -0
  185. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_banner.py +0 -0
  186. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_circuit_breaker.py +0 -0
  187. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_compat.py +0 -0
  188. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_concurrency_monitor.py +0 -0
  189. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_convert_request.py +0 -0
  190. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_convert_response.py +0 -0
  191. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_convert_sse.py +0 -0
  192. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_copilot.py +0 -0
  193. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_copilot_convert_request.py +0 -0
  194. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_copilot_convert_response.py +0 -0
  195. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_copilot_models.py +0 -0
  196. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_copilot_urls.py +0 -0
  197. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_currency.py +0 -0
  198. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_error_classifier.py +0 -0
  199. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_executor_in_flight_tracking.py +0 -0
  200. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_logging_dual_write.py +0 -0
  201. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_mixins.py +0 -0
  202. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_model_auth.py +0 -0
  203. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_model_compat.py +0 -0
  204. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_model_constants.py +0 -0
  205. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_model_mapper.py +0 -0
  206. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_model_pricing.py +0 -0
  207. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_model_token.py +0 -0
  208. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_model_vendor.py +0 -0
  209. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_native_api_base_url_override.py +0 -0
  210. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_native_api_extractors.py +0 -0
  211. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_native_api_handler.py +0 -0
  212. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_native_api_operation.py +0 -0
  213. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_native_api_routes.py +0 -0
  214. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_native_vendors.py +0 -0
  215. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_parse_usage.py +0 -0
  216. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_parse_usage_gemini.py +0 -0
  217. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_pricing.py +0 -0
  218. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_rate_limit.py +0 -0
  219. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_retry.py +0 -0
  220. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_router_chain.py +0 -0
  221. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_runtime_reauth.py +0 -0
  222. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_schema.py +0 -0
  223. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_session_aware.py +0 -0
  224. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_streaming_anthropic_compat.py +0 -0
  225. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_tier.py +0 -0
  226. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_tiers_config.py +0 -0
  227. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_time_range.py +0 -0
  228. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_token_logger.py +0 -0
  229. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_token_logger_native_columns.py +0 -0
  230. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_types.py +0 -0
  231. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_vendor_channels.py +0 -0
  232. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_vendor_helpers.py +0 -0
  233. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_vendor_streaming.py +0 -0
  234. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_vendors.py +0 -0
  235. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_zhipu.py +0 -0
  236. {coding_proxy-0.5.2a8 → coding_proxy-0.6.0}/tests/test_zhipu_concurrency.py +0 -0
@@ -28,3 +28,6 @@ config.yaml
28
28
 
29
29
  # Log files (dual-write logging)
30
30
  .logs/
31
+
32
+ # Archify authoring workspace
33
+ .archify/
@@ -2,7 +2,30 @@
2
2
 
3
3
  本文件基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/) 规范维护,版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
4
4
 
5
- ## [Unreleased]
5
+ ## [v0.6.0](https://github.com/ThreeFish-AI/coding-proxy/releases/tag/v0.6.0) - 2026-11-14
6
+
7
+ > 本周期主轴:配置系统由 YAML 迁移至 `config.db` + Dashboard Config 页(含管理面安全加固)。以下条目按重要程度排列。
8
+
9
+ - feat(config): 运行时配置源迁移至 **`$CODING_PROXY_HOME/config.db`**(默认 `~/.coding-proxy/config.db`;sqlite3、0600、密钥 Fernet 加密、主密钥 `master.key`),`config.default.yaml` 退化为随包发布的默认值基线;新增 `config/{home,defaults,normalize,store,secrets,resolver,importer,service,ui_registry}.py` 核心层与 `coding-proxy config`(`path` / `export` / `import` / `set` / `reset` / `set-secret` / `token`)子命令;写入走 per-section revision 乐观并发(冲突 409),旧 `config/loader.py` 搜索链保留为导入参考实现与等价基准、运行时不再读取;
10
+ - **升级迁移(一次性导入)**:首次 `start` 自动导入 `~/.coding-proxy/config.yaml`(或 `start -c FILE` 指定源),导入前跑旧 loader 等价校验(`ProxyConfig` 全等,不通过则以旧 YAML 只读运行、Config 页禁写);源文件不改名不改写,marker 记 sha256;此后的拒启(strict)仅限 `start -c` 显式文件、旧搜索链候选(`./config.yaml` / `~/.coding-proxy/config.yaml`,含其中即导入源的情形)、或无导入源时的上述候选与已导入版本不一致,其余来源(如另行 `config import` 的自定义路径)仅提示;
11
+ - **Breaking**:`./config.yaml` 不再被自动导入(防止第三方仓库目录下的文件被误当全局配置,首启存在时以专门话术拒启并指引 `start -c` / `config import`);「`cp config.default.yaml config.yaml` 后编辑」的旧流程整体废弃;`-c` 语义由「常规启动配置源」变为「一次性迁移导入源」;
12
+ - **密钥只写不读**:GET 仅返回 `{kind(stored/env/empty/default), env_var?, resolved, hint(尾 4 位), default_env?, recorded}`;写入用 op(`set` / `clear` / `default_env` / `env`,任意 env 绑定仅 CLI);vendor 的 `base_url` / `token_url` 变化时自动清空未显式保留的密钥(防密钥发往新目标,仅限有存储记录且新目标非包内默认端点的密钥);bootstrap 字段(`server` / `logging` / `database` / `auth` 路径类)HTTP 只读,仅 CLI `config set` 可改、需重启生效;
13
+ - feat(dashboard): 新增 **Config 页**在线编辑全部配置(Vendors / Tiers / Failover / Model Mapping / Pricing / Native API / Session Policies / System 分区,密钥三态控件,保存确认框列出将被重置的运行态与被清空的密钥,409 只重载冲突 section、422 行内定位且从不回显输入值);保存经进程内 **generation swap** 热切换生效(新配置先 preflight 构建再原子切指针,旧 generation 等待 in-flight 请求排空后关闭,上限 600s,长流式请求不受影响),无需重启;存储的配置无效时以 degraded 模式启动(仅 Dashboard 与管理 API 可用,代理接口 503 并指引修复);
14
+ - feat(security): 管理面安全加固——`/api/config*` 需 `X-Coding-Proxy-Admin` 请求头(token 存于 0600 `admin_token` 文件,`config token` 查看,常量时间比较,不接受 cookie/query);新增纯 ASGI 安全中间件:L1 全局拒绝跨站浏览器请求(`Sec-Fetch-Site` / `Origin` 校验,同时堵住既有 `POST /api/reset`、`/api/reauth/*` 的 CSRF),L2 管理面 Host 白名单(回环地址 + 新 bootstrap 字段 `server.allowed_hosts`,防 DNS rebinding);关闭 `/docs` / `/redoc`;非 dashboard 响应统一加 `CSP: sandbox` + `nosniff`;`uvicorn` 设 `proxy_headers=False`;修复 Dashboard 图表 tooltip 与 vendor name 的既有 XSS 汇点;
15
+ - security(config): 密钥泄露路径加固(I2:密钥明文不经 HTTP 响应 / 日志 / 异常离开进程)——`set` 写入边界拒绝含控制字符或非 Latin-1 字符的密钥值(422「密钥包含非法控制字符」,此类值会成为非法 HTTP header 并被异常消息携带);`/v1/messages` 流式与非流式路径的未预期异常响应改为只含异常类型名(原 `f"{type}: {exc}"` 会把 httpx 拒绝的非法 header value(内嵌密钥明文)回显给未认证客户端);executor / routes / TokenManager 的未预期异常日志改为「类型 + 堆栈帧」,不再记录 `str(exc)`;
16
+ - fix(config): `config_section` 行内数据不是有效 JSON(外部改动 / 文件损坏)时,`start` 映射为 `StoreCorruptError` 一行提示 + 退出码 2(原为裸 `JSONDecodeError` traceback);`usage --db` 正确覆盖用量数据库路径(原被当作配置文件路径传入 `load_config`);
17
+ - fix(dashboard): `/api/status` 的 `in_flight` 扣除发起查询的请求自身,空闲代理的保存确认框不再显示「进行中的请求:1 个」;离开 Config 页签时清除 URL 残留的 `section` 查询参数(避免复制分享的链接把他人带偏定位);
18
+ - refactor(auth): `RuntimeReauthCoordinator` 类文档显式标注与 `server/generations.py` 的私有属性交接契约(`_providers` / `_states` / `_locks` 等 7 个属性,重命名 / 加 `__slots__` 需同步 `_relay_reauth` / `_finish_relay` / `_forward_tokens`);
19
+ - docs: 用户文档面整体切换到 config.db 口径——重写 `arch/config-reference.md` 为「解析管线 + 存储 + 一次性导入」SSOT 口径(默认 ⊕ 覆盖 ⊕ 密钥注入 → `$tmpl` 展开),同步 `guide/{quickstart,cli-reference,dashboard,api-reference,monitoring}`(cli-reference 新增 `config` 子命令、api-reference 新增「配置管理端点」)、`user-guide`、`README` 与 `zh-CN` 镜像;修正 `circuit_breaker: None` 的语义描述(不启用熔断,兜底由 tiers 位置决定,而非「终端层」);`GET /api/config` 的 secrets 状态补充 `default_env` / `recorded` 字段与 `kind=default` 态的描述;
20
+
21
+ ## [v0.5.2](https://github.com/ThreeFish-AI/coding-proxy/releases/tag/v0.5.2) - 2026-09-10
22
+
23
+ - fix(quota-guard): `coding-proxy reset` / `POST /api/reset` 不再清空配额守卫的滑动窗口用量——根因是 `QuotaGuard.reset()` 把「状态机复位」与「用量计数清零」耦合在一个方法里(`_entries.clear()` + `_total = 0`),而窗口基线 `load_baseline()` 的唯一调用点在进程启动的 lifespan 钩子中、运行期不再回填,导致 Dashboard 的 `1d配额 45%` 徽章复位后永久停在 0%;现 `reset()` 只保留 `_transition_to(WITHIN_QUOTA)`(该方法本身已清 `_cap_error_active` 并还原探测间隔),CLI / API / Dashboard 三条路径经单一事实源同时修复。语义取舍为**如实**:用量确已超过 `token_budget × threshold_percent` 时守卫保持 `QUOTA_EXCEEDED`(不伪造用量数字),但仍清除上游 cap 错误卡死标志并把被 `Retry-After` 拉长的探测间隔还原为默认值——刻意不走 WITHIN_QUOTA → QUOTA_EXCEEDED 回环,因为 `_transition_to(EXCEEDED)` 会把 `_last_probe` 刷成当前时刻,令探测恢复凭空推迟一个 probe_interval,反复复位即可饿死探测(PR 评审发现的回归,补 2 条用例锁定);文档口径(`cli-reference.md` / `api-reference.md`)同步补明「仅复位状态、不清用量」;
24
+ - feat(dashboard): Overview 页「供应商状态」卡片标题栏右侧新增 **⟲ 状态复位** 按钮,一键把处于熔断 / 限流等异常态的供应商复位为可正常访问——调用无 body 的 `POST /api/reset`,因此**不触发重排序、不改动供应商优先级**,配合上述配额修复亦**不清空额度用量**;新增 `.btn-card-action` 卡片标题栏控件通用类(复用 `.card-title` 既有的 `justify-content: space-between`,零布局 CSS 改动)并纳入 `:focus-visible` 焦点环列表;交互沿用 `persistTierOrder` 的 in-flight 防并发范式与 `copyFromParent` 的瞬时反馈范式(复位中… → ✓ 已复位 / ✗ 失败,1.5s 还原),成功后定向重渲染供应商列表而不必等 10 分钟轮询;定向刷新 `/api/status` 失败时单独吞掉、不误报「✗ 失败」诱导重复点击(复位已生效,刷新失败仅影响展示)(实机验证);
25
+ - fix(dashboard): 修复「限速中」徽章从未渲染的问题——前端读 `rlInfo.limited`,而后端 `VendorTier.get_rate_limit_info()` 产出的键是 `is_rate_limited`,键名不匹配使 Rate Limit 异常态在 UI 上完全不可观测;补前端守卫测试锁定键名;
26
+
27
+ > [!NOTE]
28
+ > 本版为 v0.5.2 周期(v0.5.2a1–a8)的正式收口版,完整变更见上方各 alpha 段落;以下条目为 v0.5.2a8 之后的增量(#279)。
6
29
 
7
30
  ## [v0.5.2a8](https://github.com/ThreeFish-AI/coding-proxy/releases/tag/v0.5.2a8) - 2026-07-06
8
31
 
@@ -1,6 +1,6 @@
1
- Metadata-Version: 2.4
1
+ Metadata-Version: 2.5
2
2
  Name: coding-proxy
3
- Version: 0.5.2a8
3
+ Version: 0.6.0
4
4
  Summary: A High-Availability, Transparent, and Smart Multi-Vendor Proxy for Claude Code. Support Claude Plans, GitHub Copilot, Google Antigravity, ZAI/GLM, MiniMax, Qwen, Xiaomi, Kimi, Doubao...
5
5
  Project-URL: Source Code, https://github.com/ThreeFish-AI/coding-proxy
6
6
  Project-URL: User Guide, https://github.com/ThreeFish-AI/coding-proxy/blob/master/docs/user-guide.md
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.13
16
16
  Classifier: Programming Language :: Python :: 3.14
17
17
  Requires-Python: >=3.12
18
18
  Requires-Dist: aiosqlite>=0.22
19
+ Requires-Dist: cryptography>=50.0.2
19
20
  Requires-Dist: fastapi>=0.135
20
21
  Requires-Dist: httpx>=0.28
21
22
  Requires-Dist: pydantic>=2.12
@@ -86,12 +87,16 @@ uv add coding-proxy
86
87
  ```bash
87
88
  ## (Optional) Highly recommended to enable Zhipu GLM. Use env vars to defensively inject your keys
88
89
  # export ZHIPU_API_KEY="your-api-key-here"
90
+ ## ...or store the key encrypted in the config store (never echoed back)
91
+ # echo -n "sk-..." | uv run coding-proxy config set-secret vendors.zhipu.api_key --stdin
89
92
 
90
- # Start coding-proxy with the default configuration
91
- # The default config lives at: ~/.coding-proxy/config.yaml.
93
+ # Start coding-proxy with the stored configuration
94
+ # Runtime config lives in ~/.coding-proxy/config.db (SQLite, secrets encrypted);
95
+ # edit it via the Dashboard → Config page or the `coding-proxy config` CLI — no YAML to manage.
96
+ # An existing ~/.coding-proxy/config.yaml from older versions is imported once on first start.
92
97
  uv run coding-proxy start
93
98
 
94
- ## Use the `-c` flag to gracefully point to a custom config path
99
+ ## Use the `-c` flag to import a legacy YAML as the one-time migration source
95
100
  # uv run coding-proxy start -c ./coding-proxy.yaml
96
101
 
97
102
  # INFO: Started server process [1403]
@@ -121,6 +126,8 @@ Curious about your real-time token spend, latency, and circuit breaker pulse? Po
121
126
  open http://127.0.0.1:3392/dashboard
122
127
  ```
123
128
 
129
+ The **Config** tab edits the whole configuration online (vendors, tiers, failover, model mapping, pricing, native API, session policies) — saves hot-swap the running proxy with zero restarts. Unlock it once with the admin token printed by `coding-proxy config token`.
130
+
124
131
  ---
125
132
 
126
133
  ## 🛠️ The CLI Console Guide
@@ -129,7 +136,8 @@ open http://127.0.0.1:3392/dashboard
129
136
 
130
137
  | Command | Description | Example Usage |
131
138
  | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- |
132
- | `start` | **Fire up the proxy server.** Supports custom ports and configuration paths. | `coding-proxy start -p 8080 -c ~/config.yaml` |
139
+ | `start` | **Fire up the proxy server.** Supports custom ports and a one-time legacy YAML import via `-c`. | `coding-proxy start -p 8080` |
140
+ | `config` | **Manage the config store** (`~/.coding-proxy/config.db`). Sub-commands: `set`, `reset`, `set-secret` (encrypted keys), `import`/`export`, `token`. | `coding-proxy config set vendors.zhipu.timeout_ms 60000` |
133
141
  | `auth` | **Manage OAuth credentials.** Sub-commands: `login` (browser OAuth), `status` (token validity), `reauth` (re-authenticate), `logout` (clear tokens). | `coding-proxy auth login -p github` |
134
142
  | `status` | **Check proxy health.** Shows circuit breaker states (OPEN/CLOSED) and quota status across all tiers. | `coding-proxy status` |
135
143
  | `usage` | **Token Stats Dashboard.** Stalks every single token consumed, failovers triggered, and latency across day/vendor/model dimensions. | `coding-proxy usage -d 7 -v anthropic` |
@@ -200,9 +208,8 @@ graph RL
200
208
 
201
209
  To ensure this project outlives us all (long-term maintainability), we offer exhaustive, Evidence-Based documentation:
202
210
 
203
- - 📖 **[User Guide](./docs/user-guide.md)** — From installation and bare-minimum configs to the semantic breakdown of every `config.yaml` field and common troubleshooting manuals. (Currently in Chinese)
211
+ - 📖 **[User Guide](./docs/user-guide.md)** — From installation and bare-minimum setup to the semantic breakdown of every config field and common troubleshooting manuals. (Currently in Chinese)
204
212
  - 🏗️ **[Architecture Framework](./docs/framework.md)** — A meticulous decoding of underlying design patterns (Template Method, Circuit Breaker, State Machine, etc.), targeted at devs who want to peek into the matrix or contribute new vendors. (Currently in Chinese)
205
- - 🤝 **[Engineering Guidelines (AGENTS.md)](./AGENTS.md)** — The systemic context mindset and AI Agent collaboration protocol. It preaches **refactoring, reuse, and orthogonal abstractions** and serves as the ultimate guiding light for all development in this repository.
206
213
 
207
214
  ---
208
215
 
@@ -59,12 +59,16 @@ uv add coding-proxy
59
59
  ```bash
60
60
  ## (Optional) Highly recommended to enable Zhipu GLM. Use env vars to defensively inject your keys
61
61
  # export ZHIPU_API_KEY="your-api-key-here"
62
+ ## ...or store the key encrypted in the config store (never echoed back)
63
+ # echo -n "sk-..." | uv run coding-proxy config set-secret vendors.zhipu.api_key --stdin
62
64
 
63
- # Start coding-proxy with the default configuration
64
- # The default config lives at: ~/.coding-proxy/config.yaml.
65
+ # Start coding-proxy with the stored configuration
66
+ # Runtime config lives in ~/.coding-proxy/config.db (SQLite, secrets encrypted);
67
+ # edit it via the Dashboard → Config page or the `coding-proxy config` CLI — no YAML to manage.
68
+ # An existing ~/.coding-proxy/config.yaml from older versions is imported once on first start.
65
69
  uv run coding-proxy start
66
70
 
67
- ## Use the `-c` flag to gracefully point to a custom config path
71
+ ## Use the `-c` flag to import a legacy YAML as the one-time migration source
68
72
  # uv run coding-proxy start -c ./coding-proxy.yaml
69
73
 
70
74
  # INFO: Started server process [1403]
@@ -94,6 +98,8 @@ Curious about your real-time token spend, latency, and circuit breaker pulse? Po
94
98
  open http://127.0.0.1:3392/dashboard
95
99
  ```
96
100
 
101
+ The **Config** tab edits the whole configuration online (vendors, tiers, failover, model mapping, pricing, native API, session policies) — saves hot-swap the running proxy with zero restarts. Unlock it once with the admin token printed by `coding-proxy config token`.
102
+
97
103
  ---
98
104
 
99
105
  ## 🛠️ The CLI Console Guide
@@ -102,7 +108,8 @@ open http://127.0.0.1:3392/dashboard
102
108
 
103
109
  | Command | Description | Example Usage |
104
110
  | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------- |
105
- | `start` | **Fire up the proxy server.** Supports custom ports and configuration paths. | `coding-proxy start -p 8080 -c ~/config.yaml` |
111
+ | `start` | **Fire up the proxy server.** Supports custom ports and a one-time legacy YAML import via `-c`. | `coding-proxy start -p 8080` |
112
+ | `config` | **Manage the config store** (`~/.coding-proxy/config.db`). Sub-commands: `set`, `reset`, `set-secret` (encrypted keys), `import`/`export`, `token`. | `coding-proxy config set vendors.zhipu.timeout_ms 60000` |
106
113
  | `auth` | **Manage OAuth credentials.** Sub-commands: `login` (browser OAuth), `status` (token validity), `reauth` (re-authenticate), `logout` (clear tokens). | `coding-proxy auth login -p github` |
107
114
  | `status` | **Check proxy health.** Shows circuit breaker states (OPEN/CLOSED) and quota status across all tiers. | `coding-proxy status` |
108
115
  | `usage` | **Token Stats Dashboard.** Stalks every single token consumed, failovers triggered, and latency across day/vendor/model dimensions. | `coding-proxy usage -d 7 -v anthropic` |
@@ -173,9 +180,8 @@ graph RL
173
180
 
174
181
  To ensure this project outlives us all (long-term maintainability), we offer exhaustive, Evidence-Based documentation:
175
182
 
176
- - 📖 **[User Guide](./docs/user-guide.md)** — From installation and bare-minimum configs to the semantic breakdown of every `config.yaml` field and common troubleshooting manuals. (Currently in Chinese)
183
+ - 📖 **[User Guide](./docs/user-guide.md)** — From installation and bare-minimum setup to the semantic breakdown of every config field and common troubleshooting manuals. (Currently in Chinese)
177
184
  - 🏗️ **[Architecture Framework](./docs/framework.md)** — A meticulous decoding of underlying design patterns (Template Method, Circuit Breaker, State Machine, etc.), targeted at devs who want to peek into the matrix or contribute new vendors. (Currently in Chinese)
178
- - 🤝 **[Engineering Guidelines (AGENTS.md)](./AGENTS.md)** — The systemic context mindset and AI Agent collaboration protocol. It preaches **refactoring, reuse, and orthogonal abstractions** and serves as the ultimate guiding light for all development in this repository.
179
185
 
180
186
  ---
181
187
 
@@ -2,9 +2,111 @@
2
2
 
3
3
  > 维护已处理过的 Issue 摘要(问题描述、表因根因、处理方式、后续防范、同类问题影响与处理注意事项),便于同类问题的跨上下文处理。识别相同 Issue 时应在原条目追加复盘,避免同 Issue 多处维护。
4
4
 
5
+ > ID 全文唯一递增,索引行与详情块均按 ID 升序;同 Issue 增量更新既有条目,不重复登记。
6
+
7
+ ---
8
+
9
+ ## 头部索引
10
+
11
+ | ID | 标题 | 状态 | 完成时间 | 详情 |
12
+ | --- | --- | --- | --- | --- |
13
+ | I-001 | YAML 配置面整体迁移至 Dashboard Config 页(config.db + 热切换 + 密钥加密) | ✅ 已完成 | 2026-11-14 | [详情](#I-001) |
14
+ | I-002 | `coding reset` 误清配额窗口用量(Dashboard 配额百分比归零且不自愈) | ✅ 已完成 | 2026-09-10 | [详情](#I-002) |
15
+ | I-003 | Session 标题豁免前缀对 `[Session]` 兜底标题不生效(豁免仅 Level 1 生效) | ✅ 已完成 | 2026-07-02 | [详情](#I-003) |
16
+ | I-004 | Zhipu 529 过载重试退避非单调(对齐 429 指数退避语义) | ✅ 已完成 | 2026-06-30 | [详情](#I-004) |
17
+ | I-005 | streaming usage parse failed: 'NoneType' object has no attribute 'get' | ✅ 已完成 | 2026-04-28 | [详情](#I-005) |
18
+ | I-006 | anthropic 400: `tool_use` ids were found without `tool_result` blocks immediately after | ✅ 已完成 | 2026-04-27 | [详情](#I-006) |
19
+ | I-007 | count_tokens 路由 `AttributeError: 'ZhipuVendor' object has no attribute 'name'` | ✅ 已完成 | 2026-05-11 | [详情](#I-007) |
20
+ | I-008 | Gemini embedding 透传至 Vertex AI 上游返回 `request body doesn't contain valid prompts` | ✅ 已完成 | 2026-05-13 | [详情](#I-008) |
21
+ | I-009 | Dashboard Sessions 页 `Tokens` 列漏算缓存 Token | ✅ 已完成 | 2026-05-16 | [详情](#I-009) |
22
+ | I-010 | Zhipu vendor 间歇性 `[1210][API 调用参数有误]` 拒绝(诊断阶段) | ✅ 已完成 | 2026-05-26 | [详情](#I-010) |
23
+
24
+ ---
25
+
26
+ <a id="I-001"></a>
27
+ ## I-001:YAML 配置面整体迁移至 Dashboard Config 页(config.db + 热切换 + 密钥加密)
28
+
29
+ **问题描述**
30
+
31
+ 用户要求把 `config.default.yaml` 及相关配置项全部迁移到 `http://localhost:3392/dashboard?tab=config` 页管理,YAML 不再承载配置;密钥在显示与存储侧保密。原配置链路存在四类结构性风险:默认值多写漂移(Pydantic 默认 ≠ YAML 默认)、首启整份复制导致用户配置冻结在旧版本、管理 API 无鉴权可被跨站/同机进程滥用、密钥明文散落在 YAML 与 `${VAR}` 展开结果中。
32
+
33
+ **表因根因**
34
+
35
+ 配置读取(loader 深合并 + env 展开)、运行时装配(create_app 一次性快照)、持久化(无)三者耦合:所有字段在进程启动时按值拷贝进 vendor/CB/QG 对象,任何在线修改都无从落地;而 `_ensure_user_config` 首启复制又把包内默认固化成用户文件,后续版本的新增 pricing/vendors 永远到不了存量用户。
36
+
37
+ **处理方式**
38
+
39
+ 新增 `$CODING_PROXY_HOME/config.db`(sqlite3 0600、secure_delete、per-section revision 乐观并发)作为唯一配置存储:`config.default.yaml` 退化为随包基线,存储只保存与默认 diff 后的最小覆盖(dict 递归、vendors 按 vendor 类型整 dict、list 整表替换),未触碰的 section 跟随包升级。密钥按稳定路径独立存表,Fernet 加密(master.key 0600 / env 覆写 + key_check canary),HTTP 侧只写不读(keep/set/clear/default_env),vendor 目标地址(base_url/token_url)变更自动清空关联密钥,HTTP 写入含 `${` 的字面量一律拒绝(杜绝 env 外带原语)。生效走进程内 generation swap(`server/generations.py`:preflight 构建 → lifespan 独立 task → 原子切换 → 旧代排空 600s),listener 不关、长流跑完、失败保留旧代并回退 degraded 模式。管理面加双 L 防护(L1 全局跨站/Origin 拦截、L2 Host 白名单 + 本机 IP + allowed_hosts)与 admin token(`X-Coding-Proxy-Admin` 头,非常量时间比较;uvicorn `proxy_headers=False` 防 XFF 伪造 loopback)。迁移侧:首启一次性导入 `-c`/home 下 YAML,等价门(新旧 loader 产物 ProxyConfig 全等,含 ¥ 币种 PrivateAttr)不过则不建库、legacy 只读运行;源文件不改名,marker 记 sha256,漂移即拒启。CLI 新增 `config path/export/import/set/reset/set-secret/token`,bootstrap 字段(host/port/logging/database/token_store_path)只读展示、仅 CLI 可改。
40
+
41
+ **后续防范**
42
+
43
+ - 改任何「复位/重载」类语义前,先枚举状态机每条转移的附带副作用(同 I-00x 教训,本次 generation swap 的 reauth 交接即按此逐 provider 排查)。
44
+ - 密钥相关接口的错误响应必须 `errors(include_input=False)` + `hide_input_in_errors`,并拒绝控制字符(C0/C1/DEL)——否则密钥可经 422 回显或 SSE 错误流外泄(集成评审实测复现后修复)。
45
+ - 默认值只能有一个事实源;新增默认字段时同步跑 `test_config_ui_registry` 覆盖门与 native_api 双写守护测试。
46
+
47
+ **Follow-up Issues**
48
+
49
+ #282 auto-login 读 legacy 字段失效 · #283 Google reauth 阻塞事件循环 · #284 tokens.json 非原子写/丢更新 · #285 Overview 运行时调整不持久化 · #286 配置修订历史与回滚 · #287 非 loopback 管理面强鉴权
50
+
51
+ **同类问题影响**
52
+
53
+ loader/search 链、`_ensure_user_config`、`create_app` 默认参数、`usage --db`(本次顺带修复)、所有读 `~/.coding-proxy` 字面量路径的代码(统一改由 `config/home.py::proxy_home()` 推导,可用 `CODING_PROXY_HOME` 隔离/多实例)。处理时注意:旧 YAML 的 legacy flat 字段与 alias key(anthropic/zhipu)按原样保留进存储(auto-login 仍读 legacy 字段,行为不变,修复列入 follow-up issue)。
54
+
55
+ ---
56
+
57
+ <a id="I-002"></a>
58
+ ## I-002:`coding reset` 误清配额窗口用量(Dashboard 配额百分比归零且不自愈)
59
+
60
+ **问题描述**
61
+
62
+ 执行 `coding-proxy reset`(含 `-v anthropic,zhipu` 形态)后,Dashboard「供应商状态」卡片里 zhipu 的「1d配额 45%」徽章掉到 **0%**,且不会随时间恢复。用户预期该指令只复位熔断等异常状态,不应触碰额度记录。
63
+
64
+ **表因**
65
+
66
+ `/api/status` 的 `quota_guard.usage_percent` 由 `QuotaGuard.get_info()` 从内存字段 `_total` 计算,reset 后 `_total` 为 0。
67
+
68
+ **根因**
69
+
70
+ `QuotaGuard.reset()`(`routing/quota_guard.py`)把**状态机复位**与**用量计数清零**两件正交的事耦合在了一个方法里:
71
+
72
+ ```python
73
+ self._transition_to(QuotaState.WITHIN_QUOTA)
74
+ self._entries.clear() # ← 连带清空滑动窗口
75
+ self._total = 0 # ← 用量归零
76
+ ```
77
+
78
+ 之所以「不自愈」,是因为窗口基线 `load_baseline()` 的**唯一**调用点在 `server/app.py` 的 lifespan 启动钩子里 —— 进程运行期间不会再回填,只能靠新请求从 0 重新累加。文档口径(`cli-reference.md` / `api-reference.md`)自始至终只承诺「配额守卫**状态** → WITHIN_QUOTA」,从未声明会清空用量,**实现与契约不一致**。
79
+
80
+ CLI `reset` 只是 `POST /api/reset` 的瘦 HTTP 客户端,`/api/reset` 又对全部 tier 调 `quota_guard.reset()` + `weekly_quota_guard.reset()`,故 CLI 与 API 两条路径同时中招。
81
+
82
+ **处理方式**
83
+
84
+ 在 `QuotaGuard.reset()` 中删除 `_entries.clear()` / `_total = 0` 两行,只保留 `_transition_to(QuotaState.WITHIN_QUOTA)`(该方法本身已负责清 `_cap_error_active` 并还原 `_effective_probe_interval`)。**单一事实源修复**:CLI、`/api/reset`、Dashboard 新增的「状态复位」按钮三条路径自动同时受益,无需各自加 `--keep-quota` 之类开关。
85
+
86
+ 语义取舍:用量确已超过 `budget × threshold` 时,复位后守卫**保持** `QUOTA_EXCEEDED`(即「点了没反应」)。这是**如实**行为 —— 宁可不放行,也不伪造用量数字;但仍会清除 cap 错误卡死标志(`_cap_error_active`,正是 5h 限额型 vendor 的主要卡死来源)并把被 `Retry-After` 拉长的探测间隔还原为默认值。
87
+
88
+ **评审回归(PR #279)**:初版修复让 `reset()` 无条件 `_transition_to(WITHIN_QUOTA)`,用量仍超阈值时下一次判定再回落 `QUOTA_EXCEEDED` —— 而该回环会把 `_last_probe` 刷成当前时刻,令探测恢复凭空推迟一个 `probe_interval`(默认 300s),反复点击「状态复位」可**无限饿死探测**(旧实现清零用量,不存在此回环)。教训:**改「复位」语义时必须检查状态机每条转移的附带副作用**(`_transition_to` 不是纯赋值,EXCEEDED 分支带 `_last_probe = now`),修复后的 `reset()` 在用量仍超阈值时只清 `_cap_error_active` 与 `_effective_probe_interval`、不触发任何状态转移;补 `test_reset_does_not_delay_probe_when_over_budget`(mock 时钟断言探测点不被推后)与 `test_reset_still_clears_cap_stall_when_over_budget` 两条回归用例。
89
+
90
+ **后续防范**
91
+
92
+ - **写操作测试须补「不误伤其他运行时状态」守卫断言**:`tests/test_app_routes.py::test_tier_order_preserves_quota_guard` 早已是这一范式的样板,但 `/api/reset` 侧长期缺失同类断言,缺陷才得以潜伏。新增写端点时,除「改了什么」外必须同时断言「没改什么」。
93
+ - **警惕「状态机复位」与「计数清零」的耦合**:`reset()` 这类命名天然模糊。凡是同时持有状态字段与累计计数的组件(`CircuitBreaker` 的 `_failure_count` 属于状态、`QuotaGuard` 的 `_total` 属于观测数据),复位语义须显式区分二者。
94
+ - **旧测试固化了错误行为**:`test_reset_clears_all_state` 曾断言 `window_usage_tokens == 0`,等于把缺陷写成契约。修复时应先让新测试在旧实现下 FAIL,确认其真正咬住缺陷。
95
+
96
+ **同类问题影响与处理注意事项**
97
+
98
+ - **不可用线上进程验证**:`/api/reset` 会永久抹掉运行中进程的配额基线(直到重启)。验证须另起隔离实例(独立端口 + `/tmp` 数据库),严禁对用户正在使用的代理进程执行 reset。
99
+ - **`weekly_quota_guard` 复用同一个类**,修复自动覆盖周级守卫,无需单独处理。
100
+ - **`-v` 的重排序语义未变**:`-v` 仍是「提升/替换 N-tier 链路顺序」,不是「只复位这几个 vendor」的过滤器;Dashboard 按钮走无 body 路径,因此不触碰优先级。
101
+
102
+ **关联缺陷(同批修复)**
103
+
104
+ Dashboard 的「限速中」徽章读 `rlInfo.limited`,而后端 `VendorTier.get_rate_limit_info()` 产出的键是 `is_rate_limited` —— 键名不匹配导致该徽章**从未渲染过**,Rate Limit 异常态在 UI 上完全不可观测。已同步修正为 `rlInfo.is_rate_limited`。
105
+
5
106
  ---
6
107
 
7
- ## Session 标题豁免前缀对 `[Session]` 兜底标题不生效(豁免仅 Level 1 生效)
108
+ <a id="I-003"></a>
109
+ ## I-003:Session 标题豁免前缀对 `[Session]` 兜底标题不生效(豁免仅 Level 1 生效)
8
110
 
9
111
  **问题描述**
10
112
 
@@ -35,7 +137,8 @@
35
137
 
36
138
  ---
37
139
 
38
- ## Zhipu 529 过载重试退避非单调(对齐 429 指数退避语义)
140
+ <a id="I-004"></a>
141
+ ## I-004:Zhipu 529 过载重试退避非单调(对齐 429 指数退避语义)
39
142
 
40
143
  **问题描述**
41
144
 
@@ -78,7 +181,8 @@ Zhipu 配置下区间变为 `[500,1000] → [1000,2000] → [2000,4000] → [400
78
181
 
79
182
  ---
80
183
 
81
- ## streaming usage parse failed: 'NoneType' object has no attribute 'get'
184
+ <a id="I-005"></a>
185
+ ## I-005:streaming usage parse failed: 'NoneType' object has no attribute 'get'
82
186
 
83
187
  **问题描述**
84
188
 
@@ -122,7 +226,8 @@ if "usage" in data: # 仅判断 key 存在
122
226
 
123
227
  ---
124
228
 
125
- ## anthropic 400: `tool_use` ids were found without `tool_result` blocks immediately after
229
+ <a id="I-006"></a>
230
+ ## I-006:anthropic 400: `tool_use` ids were found without `tool_result` blocks immediately after
126
231
 
127
232
  **问题描述**
128
233
 
@@ -167,7 +272,8 @@ Zhipu GLM-5 流式响应偶发将 inline `tool_result` 块输出在**对应的 `
167
272
 
168
273
  ---
169
274
 
170
- ## count_tokens 路由 `AttributeError: 'ZhipuVendor' object has no attribute 'name'`
275
+ <a id="I-007"></a>
276
+ ## I-007:count_tokens 路由 `AttributeError: 'ZhipuVendor' object has no attribute 'name'`
171
277
 
172
278
  **问题描述**
173
279
 
@@ -209,7 +315,8 @@ AttributeError: 'ZhipuVendor' object has no attribute 'name'
209
315
 
210
316
  ---
211
317
 
212
- ## Gemini embedding 透传至 Vertex AI 上游返回 `request body doesn't contain valid prompts`
318
+ <a id="I-008"></a>
319
+ ## I-008:Gemini embedding 透传至 Vertex AI 上游返回 `request body doesn't contain valid prompts`
213
320
 
214
321
  **问题描述**
215
322
 
@@ -263,7 +370,8 @@ litellm 按 Google AI Studio 格式构造请求:
263
370
 
264
371
  ---
265
372
 
266
- ## Dashboard Sessions 页 `Tokens` 列漏算缓存 Token
373
+ <a id="I-009"></a>
374
+ ## I-009:Dashboard Sessions 页 `Tokens` 列漏算缓存 Token
267
375
 
268
376
  **问题描述**
269
377
 
@@ -307,7 +415,8 @@ SUM(input_tokens + output_tokens
307
415
 
308
416
  ---
309
417
 
310
- ## Zhipu vendor 间歇性 `[1210][API 调用参数有误]` 拒绝(诊断阶段)
418
+ <a id="I-010"></a>
419
+ ## I-010:Zhipu vendor 间歇性 `[1210][API 调用参数有误]` 拒绝(诊断阶段)
311
420
 
312
421
  **问题描述**
313
422
 
@@ -352,3 +461,5 @@ PR #247 (Step 1 v2) 部署后,2026-05-26 16:30–16:31 的诊断日志显示 8
352
461
  - 其他薄透传 vendor(minimax / kimi / doubao / alibaba / xiaomi)共用 `NativeAnthropicVendor._prepare_request`,若它们也开始报「参数错误」类语义拒绝,可复用本次扩展的诊断函数定位差异。
353
462
  - 若证据指向 `tools` 字段(如工具 schema 不兼容)、`metadata` 字段(如自定义键被 zhipu 拒收)等具体路径,修复时应优先复用 `convert/vendor_channels.py` 中已有的 `normalize_for_zhipu` / `strip_thinking_blocks` 工具,避免在 vendor 内部重复实现剥离逻辑。
354
463
  - 部署 Step 1 v2 后,建议观察至少 48 小时收集足够样本(>20 次失败),通过失败/成功请求形态对比统计找出**唯一差异维度**,再进入 Step 2。
464
+
465
+ ---
@@ -1,6 +1,6 @@
1
1
  # Knowledge Map(知识索引)
2
2
 
3
- > 项目所有文档的统一入口与权威索引。由 [AGENTS.md §Knowledge Map](../../AGENTS.md) 锚定,文档目录变更时**必须**即时同步更新本文件。
3
+ > 项目所有文档的统一入口与权威索引。文档目录变更时**必须**即时同步更新本文件。
4
4
  >
5
5
  > **使用方式**:按"受众 × 目的"二维定位所需文档;不确定起点时,从「入口导航」开始。
6
6
 
@@ -27,8 +27,8 @@
27
27
  | ------------------------------------------------- | --------------------------------------------------- |
28
28
  | [guide/quickstart.md](../guide/quickstart.md) | 环境要求、安装、最小配置、启动、Claude Code 集成 |
29
29
  | [guide/vendors.md](../guide/vendors.md) | 全部 9 种供应商配置详情、模型映射、定价表 |
30
- | [guide/cli-reference.md](../guide/cli-reference.md) | start / status / usage / reset / auth 全部命令 |
31
- | [guide/api-reference.md](../guide/api-reference.md) | /v1/messages、health、status、reset、dashboard 等 |
30
+ | [guide/cli-reference.md](../guide/cli-reference.md) | start / status / usage / reset / auth / config 全部命令 |
31
+ | [guide/api-reference.md](../guide/api-reference.md) | /v1/messages、status、reset、config 管理、dashboard 等 |
32
32
  | [guide/dashboard.md](../guide/dashboard.md) | Web 可视化看板功能与交互 |
33
33
  | [guide/monitoring.md](../guide/monitoring.md) | 日志、用量统计、性能调优、常见场景、故障排查 |
34
34
 
@@ -59,31 +59,21 @@
59
59
 
60
60
  ---
61
61
 
62
- ## 5. Agent 协作([docs/agents/](./))
62
+ ## 5. Agent 协作与问题档案([docs/.agents/](./))
63
63
 
64
- > AGENTS.md 工程行为准则的卫星文件,定义 AI Agent 协作过程中的规范与协议。
64
+ > 面向 AI Agent 协作与跨上下文问题沉淀的支撑文档。
65
65
 
66
- | 文档 | 主旨 |
67
- | --------------------------------------------------------------- | --------------------------------------------- |
68
- | [agents/knowledge-map.md](./knowledge-map.md) | 本文件——项目文档统一索引 |
69
- | [agents/reference-specifications.md](./reference-specifications.md) | IEEE 文献引用格式模板与实践指南 |
70
- | [agents/browser-validation.md](./browser-validation.md) | 浏览器验证协议(连通性自检、凭证管理、E2E) |
66
+ | 文档 | 主旨 |
67
+ | --------------------------------------------------- | --------------------------------------------- |
68
+ | [agents/knowledge-map.md](./knowledge-map.md) | 本文件——项目文档统一索引 |
69
+ | [agents/issue.md](./issue.md) | 已处理 Issue 摘要档案(表因、根因、防范) |
71
70
 
72
71
  ---
73
72
 
74
- ## 6. 问题档案
73
+ ## 6. 工程规范(顶层)
75
74
 
76
75
  | 文档 | 主旨 |
77
76
  | --------------------------------- | ----------------------------------------------------- |
78
- | [docs/issue.md](../issue.md) | 已处理 Issue 摘要档案(表因、根因、防范) |
79
-
80
- ---
81
-
82
- ## 7. 工程规范(顶层)
83
-
84
- | 文档 | 主旨 |
85
- | --------------------------------- | ----------------------------------------------------- |
86
- | [AGENTS.md](../../AGENTS.md) | 工程行为准则与 AI Agent 协作协议(与 CLAUDE.md 同源) |
87
77
  | [CHANGELOG.md](../../CHANGELOG.md)| 版本历史与变更日志 |
88
78
 
89
79
  ---
@@ -91,5 +81,5 @@
91
81
  ## 维护约束
92
82
 
93
83
  1. **同步原则**:新增/删除/重命名 `docs/` 下任意 .md 文件时,**必须**同步本索引。
94
- 2. **路径基准**:本文件位于 `docs/agents/`,所有相对路径以此为基准(向上一级 `../` 访问 `docs/`,向上两级 `../../` 访问仓库根)。
84
+ 2. **路径基准**:本文件位于 `docs/.agents/`,所有相对路径以此为基准(向上一级 `../` 访问 `docs/`,向上两级 `../../` 访问仓库根)。
95
85
  3. **链接验证**:维护者修改本文件后应通过 grep 自检:所有 `[...](path)` 中的 `path` 文件存在。
@@ -22,23 +22,50 @@
22
22
 
23
23
  `config/schema.py` 作为聚合入口点 re-export 所有符号,并保留 `ProxyConfig` 顶层模型及旧格式迁移逻辑。
24
24
 
25
+ 运行时配置的存储与解析由 `config/` 下的新增模块承担:
26
+
27
+ | 模块 | 文件 | 职责 |
28
+ | ----------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
29
+ | **home** | [`config/home.py`](../../src/coding/proxy/config/home.py) | `proxy_home()`(env `CODING_PROXY_HOME` → 默认 `~/.coding-proxy`)与派生路径 |
30
+ | **defaults** | [`config/defaults.py`](../../src/coding/proxy/config/defaults.py) | 随包 `config.default.yaml` 基线的解析(默认值单一事实源) |
31
+ | **store** | [`config/store.py`](../../src/coding/proxy/config/store.py) | `config.db`(sqlite3)读写、per-section revision 乐观并发、损坏/占用错误分类 |
32
+ | **secrets** | [`config/secrets.py`](../../src/coding/proxy/config/secrets.py) | 密钥三态记录(stored 密文 / env 变量 / empty)、Fernet 加解密、主密钥管理 |
33
+ | **resolver** | [`config/resolver.py`](../../src/coding/proxy/config/resolver.py) | `resolve_config()`:默认 ⊕ 覆盖 ⊕ 密钥注入 → `$tmpl` 展开 → `ProxyConfig` |
34
+ | **importer** | [`config/importer.py`](../../src/coding/proxy/config/importer.py) | 旧 YAML 一次性导入(等价校验)、`boot()` 首启流程、YAML 一致性检查 |
35
+ | **service** | [`config/service.py`](../../src/coding/proxy/config/service.py) | `ConfigService`:Dashboard / CLI 共用的读写与校验服务 |
36
+ | **ui_registry** | [`config/ui_registry.py`](../../src/coding/proxy/config/ui_registry.py) | Dashboard Config 页字段元数据(label / widget / 中文说明) |
37
+ | **loader** | [`config/loader.py`](../../src/coding/proxy/config/loader.py) | 旧 YAML 搜索链读取,保留为导入参考实现与等价基准(运行时不再使用) |
38
+
25
39
  ---
26
40
 
27
- ## 2. 配置搜索优先级
41
+ ## 2. 配置解析与存储
28
42
 
29
- [`config/loader.py`](../../src/coding/proxy/config/loader.py) 按以下顺序搜索配置文件:
43
+ 运行时配置源为 **`$CODING_PROXY_HOME/config.db`**(默认 `~/.coding-proxy/config.db`,sqlite3、0600);`config.default.yaml` 退化为随包发布的默认值基线,用户不再编辑任何 YAML。
30
44
 
31
- ```mermaid
32
- flowchart TD
33
- A["CLI --config 参数<br/>(显式指定)"] -->|"未指定"| B["./config.yaml<br/>(项目根目录)"]
34
- B -->|"不存在"| C["~/.coding-proxy/config.yaml<br/>(用户目录)"]
35
- C -->|"不存在"| D["Pydantic 默认值"]
45
+ ![配置解析与存储](../diagrams/config-resolution-storage/config-resolution-storage.svg)
36
46
 
37
- style A fill:#1a5276,color:#fff
38
- style D fill:#7b241c,color:#fff
39
- ```
47
+ 上图(配置源 → 合并 → 密钥注入 → `$tmpl` 展开 → `ProxyConfig` 校验 → 运行时热切换,含三条写入路径与导入门)为双主题 SVG,深浅模式自适应;交互版与图源见 [`docs/diagrams/config-resolution-storage/`](../diagrams/config-resolution-storage/)。
48
+
49
+ **写入路径**(仅三条,均经 `ConfigService` 校验后持久化,保存即在进程内热切换生效):
50
+
51
+ - Dashboard → Config 页(`PUT /api/config`,需 `X-Coding-Proxy-Admin` 头)
52
+ - CLI:`coding-proxy config set / reset / set-secret`(含 bootstrap 字段)
53
+ - `coding-proxy config import`(旧 YAML 一次性导入,见 §2.2)
54
+
55
+ **存储模型**:`config_section` 行存在 = 该 section 被覆盖,删除行 = 恢复默认;`secret` 表按路径独立存放密钥(Fernet 加密,主密钥为 `$CODING_PROXY_HOME/master.key` 或 env `CODING_PROXY_MASTER_KEY`),Reset section 不会丢失密钥;per-section revision 支持乐观并发(冲突返回 409)。
56
+
57
+ **环境变量展开**:语法 `${VARIABLE_NAME}`,递归处理 dict/list/str,未定义变量展开为空串。模板仅随包默认值与旧 YAML 导入进入存储;Dashboard / CLI 写入的字符串一律按字面量保存,不会再被展开。
58
+
59
+ ### 2.1 密钥(只写不读)
60
+
61
+ 密钥字段(各供应商 `api_key` / `github_token` / `client_id` / `client_secret` / `refresh_token`、`auth.google_client_secret`)在存储中脱离 section 文档:GET 只返回 `{kind, env_var?, resolved, hint, default_env?, recorded}`(`kind` 含 `stored` / `env` / `empty` / `default` 四态;`recorded` 标识是否存在密钥记录,前端据此预测「目标地址变更 → 清空」;长度 ≥ 16 才展示尾 4 位;完整载荷见 [API 参考 §11.1](../guide/api-reference.md#111-get-apiconfig));写入用 op 表达(`set` / `clear` / `default_env` / `env`),值从不回显。vendor 的 `base_url` / `token_url` 变化时该 vendor 的已存密钥自动清空(防密钥发往新目标),同一请求显式 `set` 可保留;新目标即包内默认端点(`reset` / 改回默认)时保留密钥。
62
+
63
+ ### 2.2 旧 YAML 一次性导入(boot)
40
64
 
41
- **环境变量展开**:语法 `${VARIABLE_NAME}`,递归处理 dict/list/str,未定义变量保留原文。
65
+ - 首次 `start`(或 `config import`)时,源为 `start -c FILE` 指定的路径或 `~/.coding-proxy/config.yaml`(存在时);`./config.yaml` **不会**被自动导入。
66
+ - 导入前跑旧 loader 做等价校验:`resolve_config() == legacy load_config(source)`;不通过则不建库,本次以旧 YAML 只读运行(Config 页显示失败字段路径并禁写)。
67
+ - 源文件不改名、不改写;marker 记录 sha256。拒启(strict)覆盖:`start -c` 显式指定的文件(始终 strict,与导入来源无关);该文件即导入源(marker.source 指向它);或存储无导入源(`imported_from` 为 None,含首启)时旧版会读取的 `./config.yaml` / `~/.coding-proxy/config.yaml`;其余情形(如经 `config import /tmp/custom.yaml` 导入后,home 下遗留的旧 YAML 被修改)只提示「不一致,确认无用后请删除」,不拒启。
68
+ - 旧 `config/loader.py` 搜索链(`./config.yaml` → `~/.coding-proxy/config.yaml` → Pydantic 默认)保留为导入参考实现与测试基准,运行时不再读取。
42
69
 
43
70
  ---
44
71
 
@@ -50,29 +77,33 @@ flowchart TD
50
77
  | ------ | ---- | ------------- | -------- |
51
78
  | `host` | str | `"127.0.0.1"` | 监听地址 |
52
79
  | `port` | int | `3392` | 监听端口 |
80
+ | `allowed_hosts` | list[str] | `[]` | 管理面(Dashboard / 非透传 `/api/*`)Host 白名单的额外条目;`127.0.0.1` / `localhost` / `::1` 恒允许,绑定 IP 的本机访问亦放行。bootstrap 字段,经 `coding-proxy config set` 修改后需重启 |
53
81
 
54
82
  ### 3.2 DatabaseConfig
55
83
 
56
- | 字段 | 类型 | 默认值 | 说明 |
57
- | -------------------------- | ---- | ----------------------------- | --------------------- |
58
- | `path` | str | `"~/.coding-proxy/usage.db"` | SQLite 数据库文件路径 |
59
- | `compat_state_path` | str | `"~/.coding-proxy/compat.db"` | 兼容性会话存储路径 |
60
- | `compat_state_ttl_seconds` | int | `86400` | 兼容性会话 TTL(秒) |
84
+ | 字段 | 类型 | 默认值 | 说明 |
85
+ | -------------------------- | ---- | ----------------------------- | --------------------------------------------------- |
86
+ | `path` | str | `"~/.coding-proxy/usage.db"` | SQLite 数据库文件路径(派生自 `$CODING_PROXY_HOME`) |
87
+ | `compat_state_path` | str | `"~/.coding-proxy/compat.db"` | 兼容性会话存储路径(同上派生) |
88
+ | `compat_state_ttl_seconds` | int | `86400` | 兼容性会话 TTL(秒) |
61
89
 
62
90
  ### 3.3 LoggingConfig
63
91
 
64
92
  | 字段 | 类型 | 默认值 | 说明 |
65
93
  | -------------- | ----------- | --------- | ---------------------------------------- |
66
94
  | `level` | str | `"INFO"` | 控制台日志级别 |
67
- | `file` | str \| null | `null` | 文件日志路径(`null` 时输出到控制台) |
95
+ | `file` | str \| null | `null` | 文件日志路径;`null` 时 CLI 启动回落 `.logs/coding-proxy.log`,空串 `""` 禁用文件日志(仅控制台) |
68
96
  | `max_bytes` | int | `5242880` | 单个日志文件最大字节数(5 MB),触发轮转 |
69
97
  | `backup_count` | int | `5` | 保留的已压缩备份文件数 |
70
98
 
71
99
  ### 3.4 AuthConfig
72
100
 
73
- | 字段 | 类型 | 默认值 | 说明 |
74
- | ------------------ | ---- | ------ | ------------------------------------ |
75
- | `token_store_path` | str | `""` | Token Store 文件路径(空则使用默认) |
101
+ | 字段 | 类型 | 默认值 | 说明 |
102
+ | ------------------- | ---------------- | ---------------------------------- | ---------------------------------------------------------- |
103
+ | `token_store_path` | str | `~/.coding-proxy/tokens.json`(派生自 `$CODING_PROXY_HOME`) | Token Store 文件路径 |
104
+ | `github_client_id` | str | 公开 ID | GitHub OAuth Client ID(隐藏字段,仅导入/导出往返) |
105
+ | `google_client_id` | str | 内置公开凭据 | Google OAuth Client ID(开箱即用,可覆盖) |
106
+ | `google_client_secret` | 密钥 | 内置公开凭据(开箱即用) | 密钥字段,经 `config set-secret` / Dashboard 写入 |
76
107
 
77
108
  ---
78
109
 
@@ -89,13 +120,13 @@ flowchart TD
89
120
 
90
121
  ## 5. VendorConfig 弹性字段
91
122
 
92
- | 字段 | 类型 | 默认值 | 说明 |
93
- | -------------------- | -------------- | -------------------- | ----------------------------------- |
94
- | `circuit_breaker` | config \| None | `None` | 熔断器配置(None = 终端层) |
95
- | `retry` | config | `RetryConfig()` | 重试策略配置 |
96
- | `quota_guard` | config | `QuotaGuardConfig()` | 日度配额守卫配置 |
97
- | `weekly_quota_guard` | config | `QuotaGuardConfig()` | 周度配额守卫配置 |
98
- | `concurrency` | config \| None | `None` | `[zhipu]` 每模型并发限制(详见 5.5) |
123
+ | 字段 | 类型 | 默认值 | 说明 |
124
+ | -------------------- | -------------- | -------------------- | ------------------------------------------- |
125
+ | `circuit_breaker` | config \| None | `None` | 熔断器配置(None = 不启用熔断,兜底由 tiers 中的位置决定) |
126
+ | `retry` | config | `RetryConfig()` | 重试策略配置 |
127
+ | `quota_guard` | config | `QuotaGuardConfig()` | 日度配额守卫配置 |
128
+ | `weekly_quota_guard` | config | `QuotaGuardConfig()` | 周度配额守卫配置 |
129
+ | `concurrency` | config \| None | `None` | `[zhipu]` 每模型并发限制(详见 5.5) |
99
130
 
100
131
  <a id="elastic-params"></a>
101
132
 
@@ -153,7 +184,7 @@ flowchart TD
153
184
  | `default` | int | `3` | 全局默认并行度(适用于所有未在 `models` 中显式覆盖的模型);取值范围 `[1, 20]` |
154
185
  | `models` | map[str → int] | `{}` | 按映射后模型名(如 `glm-5v-turbo` / `glm-5.1` / `glm-4.5-air`)自定义并行度上限 |
155
186
 
156
- YAML 示例:
187
+ 配置示例(Dashboard → Config 或 `config set vendors.zhipu.concurrency '{...}'`):
157
188
 
158
189
  ```yaml
159
190
  - vendor: zhipu
@@ -235,9 +266,9 @@ YAML 示例:
235
266
 
236
267
  ---
237
268
 
238
- ## 9. vendors 列表格式(推荐)
269
+ ## 9. vendors 列表格式
239
270
 
240
- 推荐使用 `vendors` 列表格式,每个 vendor 自包含其弹性配置:
271
+ `vendors` 以列表形式定义所有供应商,每个 vendor 自包含其弹性配置(Dashboard → Config 的 Vendors 分区或 `config set vendors` 以同一结构读写;`config export` 导出的也是该格式):
241
272
 
242
273
  ```yaml
243
274
  vendors:
@@ -255,7 +286,7 @@ vendors:
255
286
 
256
287
  - vendor: copilot
257
288
  enabled: false
258
- github_token: "${GITHUB_TOKEN}"
289
+ # 密钥字段在导出中只会是 ${VAR} 或 <redacted>;实际值经 config set-secret / Dashboard 写入
259
290
  account_type: individual
260
291
  circuit_breaker:
261
292
  failure_threshold: 3
@@ -266,19 +297,17 @@ vendors:
266
297
 
267
298
  - vendor: zhipu
268
299
  enabled: true
269
- api_key: "${ZHIPU_API_KEY}"
270
- # 无 circuit_breaker -> 终端层
300
+ # 无 circuit_breaker -> 不启用熔断;是否兜底由 tiers 中的位置决定
271
301
 
272
302
  - vendor: minimax
273
303
  enabled: false
274
- api_key: "${MINIMAX_API_KEY}"
275
304
 
276
305
  tiers: [anthropic, copilot, zhipu] # 显式优先级(可选)
277
306
  ```
278
307
 
279
- ### Legacy Flat 格式(向后兼容)
308
+ ### Legacy Flat 格式(仅导入兼容)
280
309
 
281
- 旧的 flat 格式字段(`primary`/`copilot`/`antigravity`/`fallback`/`circuit_breaker`/`*_quota_guard`)仍受支持,通过 `ProxyConfig._migrate_legacy_fields()` 自动迁移为 vendors 列表格式。
310
+ 旧的 flat 格式字段(`primary`/`copilot`/`antigravity`/`fallback`/`circuit_breaker`/`*_quota_guard`)在一次性导入时经 `ProxyConfig._migrate_legacy_fields()` 自动迁移为 vendors 列表格式,随导入存入 config.db;此后不再出现在写入路径中。
282
311
 
283
312
  迁移规则:
284
313
  1. `anthropic` 字段名 → `primary`
@@ -324,7 +353,7 @@ tiers: [anthropic, copilot, zhipu] # 显式优先级(可选)
324
353
  由 `NativeApiConfig._apply_env_overrides` `@model_validator(mode="after")` 注入:
325
354
 
326
355
  ```text
327
- env var(运行时) > YAML 显式字段(部署时) > Pydantic 内置默认(兜底)
356
+ env var(运行时) > 存储的显式字段(Dashboard / CLI 配置) > Pydantic 内置默认(兜底)
328
357
  ```
329
358
 
330
359
  | 环境变量 | 覆写目标 |