refactor(providers)!: make provider behavior explicit in imported profiles
还没有人认领这个 Issue。
评估
- 难度
- 5/5
- 预计耗时
- 一周以上
- 新手友好度
- 35/100
- Issue 类型
- 重构
- 描述清晰度
- 基本清楚
- 活跃度
- 活跃
- 技术栈
- rust
调研方向
从 crates/openshell-providers/src/lib.rs 中的 ProviderRegistry::new 和 inject_env_for_profile_id 开始,然后检查 google_cloud.rs、vertex.rs、proto/openshell.proto 以及 middleware services 的入口点。在更改 schema 或文档之前,盘点每一种已编译行为并确定其处理方式。完成的标准是:forked profile IDs 保持原有行为,缺失的 adapters fail closed,过时的 discovery APIs 得到解决,并记录 middleware 的分类。
由索引模型根据 Issue 内容生成。
描述
Sub-issue of #3171 (provider boundary in step 5). Follows #3299 / PR #3383, which made provider profiles import-only. Coordinated pre-0.1.0 breaking change under #2565.
User Story
As an operator, I want an imported provider profile to declare every behavior it activates, so I can inspect, fork, and rename the profile without silently changing the sandbox environment.
Problem Statement
#3299 removed the compiled provider profile catalog, but two compiled adapters remain:
google-cloudprojects provider config into GCP SDK variables and setsGCE_METADATA_HOST.google-vertex-aiprojects project and region config into GCP and Vertex variables and sets aGOOSE_PROVIDERdefault.
ProviderRegistry::inject_env_for_profile_id selects these adapters by the resolved profile ID. Importing the same profile as google-cloud and acme-gcp therefore produces different environments even though the imported definitions are identical.
Other provider-specific behavior is also compiled rather than declared: Vertex discovery scans a fixed list of config variables, and child-environment preparation contains GCP-specific metadata and non-secret configuration handling. ProviderProfile can declare credential environment variables, but not non-secret config projection, fixed non-secret values, discovery config keys, or a required platform adapter.
Impact / Why This Matters
An imported profile is not currently its complete definition. Operators must preserve canonical IDs and know release-specific implementation details, or provider creation succeeds while the workload later fails because expected SDK configuration is absent. This contradicts the import-only contract and makes profile forks unsafe.
Proposed Design
Inventory every compiled provider behavior reachable from an imported profile and give it one disposition:
- Express in the profile. Add bounded declarative fields for generic non-secret behavior such as config-to-environment projection, fixed values, and discovery config keys. Do not introduce templating or scripting.
- Declare a platform adapter. If behavior is genuinely platform-specific, the profile names the required adapter. Import or attachment fails with a bounded diagnostic when the adapter is unavailable.
- Remove it. Delete behavior or APIs with no remaining caller, including
ProviderDiscoverySpecanddiscover_with_specunless a supported use is identified.
Projection must preserve the existing rule that caller-supplied environment values win. Linting must reject collisions between non-secret projection and credential env_vars.
Update the Google Cloud and Vertex examples so their YAML describes their complete environment and discovery effects. A fork imported under a different ID must behave identically to the canonical example.
Credential refresh strategies are out of scope because profiles already declare them.
Acceptance Criteria
- Every compiled provider behavior reachable from an imported profile is inventoried as profile-declared, named platform adapter, or removed.
- No provider behavior activates from the profile ID alone.
- The Google Cloud and Vertex examples declare their complete non-secret environment and discovery effects.
- A profile forked under another ID produces the same sandbox environment and discovery behavior as the canonical profile.
- Environment projection never overwrites an existing value.
- Import or attachment fails with a bounded diagnostic when a declared platform adapter is unavailable.
- Profile lint rejects unknown adapters and collisions between non-secret projection and credential environment variables.
-
ProviderDiscoverySpecanddiscover_with_specare removed or have a documented supported caller. -
ProviderProfile.sourceandresource_versiondocumentation no longer refers to built-in profiles orbuiltinprovenance. - Provider examples, architecture/user documentation, and
0.1.0migration notes describe the resulting contract. - Tests cover profile/proto round trips, forked-ID equivalence, collision handling, non-overwrite semantics, and unavailable adapters.
Alternatives Considered
- Delete both adapters: restores a clean boundary but breaks existing GCP and Vertex workloads at upgrade.
- Document ID-keyed behavior only: leaves profile forks behaviorally different and the binary authoritative for part of the profile definition.
- Add a general templating language: unnecessarily turns reviewable profile data into executable configuration; bounded projection covers the observed generic cases.
- Restore aliases: cannot support an unbounded operator catalog and reintroduces hidden ID coupling.
Technical Notes
crates/openshell-providers/src/lib.rs:ProviderRegistryregisters the two remaining adapters and selects them by exact profile ID.crates/openshell-providers/src/discovery.rs:discover_from_profilespecial-casesgoogle-vertex-aiconfig keys.crates/openshell-core/src/provider_credentials.rs: child environment preparation contains GCP-specific metadata and non-secret resolution.crates/openshell-server/src/grpc/provider.rs: provider environment assembly and key-collision validation are the runtime integration points.proto/openshell.protoandcrates/openshell-providers/src/profiles.rs: the public profile schema and YAML/protobuf conversion currently lack this declaration surface.
Checklist
- Existing issues and architecture documentation reviewed
- Design proposal; implementation planning follows human disposition
- 主要语言
- Rust
- 星标
- 8.7k
- 派生
- 1.3k
- 平均合并
- 2 天 6 小时
- 30 天内合并 PR
- 301
贡献指南
从这里开始
- 先读完整个 Issue,再读项目的贡献指南。
- 在 Issue 下留言说明你要接手 —— 这能避免两个人做同样的事。
- Fork 仓库,在一个分支上完成修改。
- 提交 Pull Request,并在描述里引用这个 Issue 编号。
NVIDIA/OpenShell 的其他 Issue
-
area:docs
难度 1/5 1 小时以内 新手友好度 88/100
-
state:triage-needed
难度 2/5 1-3 小时 新手友好度 82/100
-
area:cli state:validated
难度 2/5 1-3 小时 新手友好度 72/100
-
state:triage-needed
难度 1/5 1 小时以内 新手友好度 90/100
-
area:build spike state:review-ready state:stale
难度 2/5 半天 新手友好度 68/100
相似的 Issue
-
难度 2/5 1-3 小时 新手友好度 75/100
TheLarkInn/aipm#2413 ·
-
documentation
难度 1/5 1 小时以内 新手友好度 90/100
alexgorbatchev/simple-ptt#15 ·
-
tooling
难度 2/5 1-3 小时 新手友好度 75/100
-
todo:ticket
难度 2/5 1-3 小时 新手友好度 70/100
-
难度 2/5 1-3 小时 新手友好度 75/100
taikoxyz/taiko-mono#22168 · 1 条评论 ·