feat(models): establish capacity and capability governance

[JasonW404]

概要

建立模型上下文容量与能力治理的基础层，为后续请求预算、恢复和用量展示提供统一、可追溯的数据契约。

新增能力

• 独立表达上下文窗口、最大输出、推理能力和 Prompt Cache 能力。
• 引入带来源与可信度的容量解析、模型身份匹配和版本化能力目录。
• 增加可选的 Provider token count 探测；探测失败不会阻塞模型管理。
• 增加容量与能力字段的兼容性数据库迁移。

对旧行为的调整

• 不再把未知容量或能力猜测成已支持；未知状态保持为空并可观测。
• 将原先分散的容量常量和匹配逻辑收敛为 SDK/服务层统一契约。
• 保留旧模型记录和旧 max_tokens 数据的读取兼容性。

对 Nexent 的提升

为多供应商模型提供稳定的能力基线，减少错误配置和静默推断，为长会话上下文治理建立可信输入。

规模与依赖

• 44 个文件，4,265 行新增、222 行删除（4,487 行变更）。
• 基于 develop，无本系列前置 PR；后续依次为 feat(models): integrate governed model configuration #3849、feat(context): meter final requests and recover safely #3850、feat(context): persist and present agent run usage #3851。
• SPEC：Model Capacity Governance（基础部分）、Model Feature Capability Discovery。

验证

• 容量预算/解析、能力画像、模型身份、Prompt Cache、tokenizer 单测通过。
• Provider、目录、治理、健康、建议、校验、匹配和 count probe 服务测试通过；count probe 31 个用例、目标模块覆盖率 99%。
• 两项数据库迁移契约测试通过。
• 已从最新 origin/develop 执行本地 git merge --squash；最终结果提交 bb43dbcf0，测试通过且文件树与本分支一致。
• 根据人工 review 补充了 backend-to-SDK lazy import 边界说明；suggestion 47 和轻量 model-management 76 个测试通过。
• 修复 Sonar 指出的输出保护变量覆盖和模型 ID 正则回溯风险，并完成全套复验。
• 修复全量 CI 中轻量 model-management 导入路径与 SDK matcher 的边界冲突；PR1 树上的 model-management 86 个测试通过。
• 新增 DNS 失败、SSRF、IPv6、HTTP 超时/连接错误、超大与非法响应等安全边界测试。

合并说明

本 PR 是堆叠变更的第一层。后续 PR 应在本 PR 合并后依次重定向到 develop。

[Copilot]

🟡 Changes recommended

The new capacity validation logic is inconsistent with the updated W2 budget semantics and may incorrectly reject (or force fallback for) otherwise valid configurations.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR establishes a versioned, auditable governance foundation for model capacity (context window / input+output limits / tokenizer) and model feature capabilities (reasoning + prompt cache) across the SDK and backend, including optional token-count endpoint probing and database contract migrations to persist the new metadata.

Changes:

• Adds SDK-level, versioned contracts for model identity parsing, tokenizer profile/conformance governance, and feature-capability resolution (provider extensions + catalog precedence).
• Updates backend provider ingestion and model persistence to attach sanitized feature-capability metadata, plus new services for profile matching, governance/adoption, validation, health classification, and catalog staging.
• Introduces nullable/idempotent DB migrations and extensive tests covering governance, discovery, and safety/secret-sanitization constraints.

File summaries

File	Description
test/sdk/core/models/test_tokenizer_governance.py	Adds tokenizer profile/conformance governance tests and fallback behavior assertions.
test/sdk/core/models/test_prompt_cache.py	Updates prompt-cache tests to require model-level explicit profiles (provider-only disabled).
test/sdk/core/models/test_model_identity.py	Adds tests for separator-aware, versioned model identity parsing and alias safety checks.
test/sdk/core/models/test_feature_capability.py	Adds tests for provider extension extraction, normalization, and catalog precedence resolution.
test/sdk/core/models/test_capacity_resolver.py	Updates capacity resolver expectations for derived output protection and legacy override handling.
test/sdk/core/models/test_capacity_budget.py	Updates W2 safe input budget tests to reflect new reserve/output behavior semantics.
test/sdk/core/models/test_capability_profile_governance.py	Adds tests for capability profile governance validation and production catalog invariants.
test/deploy/test_model_feature_capability_migration.py	Verifies feature-capability migration is nullable/idempotent and secret-free.
test/deploy/test_context_budget_p1_migration.py	Verifies capacity-governance migration is nullable/idempotent and secret-free.
test/backend/services/test_model_token_count_probe_service.py	Adds tests for token-count probe behavior, SSRF defenses, caching, and log sanitization.
test/backend/services/test_model_provider_service.py	Adapts provider-service tests for persisted provider capacity candidates + feature metadata.
test/backend/services/test_model_profile_match_service.py	Adds tests ensuring capacity-match does not imply tokenizer-match and serialization versioning.
test/backend/services/test_model_capacity_validation_service.py	Adds tests for capacity contract validation and sanitized auditing behavior.
test/backend/services/test_model_capacity_suggestion_service.py	Expands capacity suggestion tests for alias/exclusion matching and response shape changes.
test/backend/services/test_model_capacity_health_service.py	Adds deterministic capacity health classification tests (freshness/probe/estimated).
test/backend/services/test_model_capacity_governance_service.py	Adds tests for field-level provenance merge rules and catalog adoption flows.
test/backend/services/test_model_capacity_catalog_service.py	Adds tests for trusted catalog staging and candidate refresh without mutating active catalog.
test/backend/services/providers/test_dashscope_provider.py	Updates DashScope provider tests for new capacity hint extraction paths and fields.
test/backend/consts/test_model_feature_capabilities.py	Adds coverage tests ensuring feature capability catalog rules resolve as intended per factory.
sdk/nexent/core/models/tokenizer_registry.py	Introduces tokenizer profiles, match results, conformance reporting, and independent resolution logic.
sdk/nexent/core/models/prompt_cache.py	Changes prompt-cache profile resolution to require model-level explicit profiles; keeps constants for import compatibility.
sdk/nexent/core/models/model_identity.py	Adds separator-aware canonical identity parsing and safe-alias comparison logic with matcher versioning.
sdk/nexent/core/models/feature_capability.py	Adds capability extraction from provider model objects + normalized resolution against exact/family catalogs.
sdk/nexent/core/models/capacity_resolver.py	Adds output-protection derivation and adjusts requested output handling + catalog governance validation helpers.
sdk/nexent/core/models/capacity_budget.py	Bumps W2 resolver version and updates safe-input budget calculation semantics/reserve basis representation.
deploy/sql/migrations/v2.6.0_0903_model_feature_capabilities.sql	Adds nullable JSONB column for persisted feature capability metadata.
deploy/sql/migrations/v2.6.0_0903_model_capacity_governance.sql	Adds nullable governance/identity/tokenizer/probe metadata columns to model_record_t.
backend/services/providers/tokenpony_provider.py	Surfaces feature capability hints alongside capacity hints during provider model ingestion.
backend/services/providers/silicon_provider.py	Surfaces feature capability hints alongside capacity hints during provider model ingestion.
backend/services/providers/modelengine_provider.py	Surfaces feature capability hints alongside capacity hints during provider model ingestion.
backend/services/providers/dashscope_provider.py	Updates capacity hint extraction nesting and adds feature capability hint extraction.
backend/services/providers/base.py	Adds helper to extract allow-listed feature capability extensions from raw provider payloads.
backend/services/model_token_count_probe_service.py	Adds safe, SSRF-defended token-count probe with sanitized metadata + caching and controlled protocol probing.
backend/services/model_provider_service.py	Resolves and attaches feature capability metadata per model; persists normalized metadata into ModelRequest.
backend/services/model_profile_match_service.py	Adds independent capacity/tokenizer profile resolution and serialization for governance metadata.
backend/services/model_capacity_validation_service.py	Adds contract validation and read-only audit classification for persisted capacity records.
backend/services/model_capacity_suggestion_service.py	Switches normalization/matching to identity-aware comparisons; adds explicit alias/exclusion matching and auto-applicable source handling.
backend/services/model_capacity_health_service.py	Adds catalog freshness and deterministic health classification for capacity governance workflows.
backend/services/model_capacity_governance_service.py	Adds field-level provenance merging, legacy normalization, adoption preview, and version-checked adoption application.
backend/services/model_capacity_catalog_service.py	Adds trusted catalog staging and candidate refresh mechanism guarded by signature verification and revision checks.
backend/consts/model.py	Extends request/response schemas for feature metadata, governance fields, and adoption/probe request payloads.
backend/consts/model_feature_capabilities.py	Adds governed feature capability catalog with evidence links, exact entries, and family rules.
backend/consts/exceptions.py	Adds ModelCapacityConfigError for stable reason codes and field-scoped validation errors.
backend/consts/capability_profiles.py	Bumps catalog revision and enriches capability profiles with governance declarations (aliases/evidence/verified_at/etc.).

Review details

• Files reviewed: 44/44 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[codecov]

Codecov Report

❌ Patch coverage is 89.32874% with 124 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
sdk/nexent/core/models/feature_capability.py	75.84%	32 Missing and 18 partials ⚠️
...kend/services/model_capacity_governance_service.py	87.95%	10 Missing and 10 partials ⚠️
...kend/services/model_capacity_validation_service.py	79.26%	8 Missing and 9 partials ⚠️
backend/services/model_capacity_health_service.py	89.04%	4 Missing and 4 partials ⚠️
sdk/nexent/core/models/capacity_resolver.py	88.33%	3 Missing and 4 partials ⚠️
sdk/nexent/core/models/model_identity.py	93.87%	3 Missing and 3 partials ⚠️
sdk/nexent/core/models/tokenizer_registry.py	93.02%	3 Missing and 3 partials ⚠️
backend/services/model_capacity_catalog_service.py	92.85%	2 Missing and 2 partials ⚠️
backend/services/model_profile_match_service.py	96.22%	1 Missing and 1 partial ⚠️
backend/services/model_provider_service.py	77.77%	1 Missing and 1 partial ⚠️
... and 2 more

📢 Thoughts on this report? Let us know!

[JasonW404]

补充 2026-09-03 变更：已确认支持的模型能力现在由统一 effective-policy resolver 默认开启。reasoning 的 effort 型能力采用目录声明的默认值（当前受治理 profile 为 medium），cache 支持时默认启用；未知或不支持能力仍 fail closed。新增 preference narrowing 契约，未来用户偏好只能关闭/收窄能力，不能绕过 capability profile。相关 capability/catalog UT 通过。