[Feature]: 统一外部 Provider 导入为共享 Adapter 框架 / Unify external provider imports under a shared adapter framework

[Sun-sunshine06]

[Feature]: 统一外部 Provider 导入为共享 Adapter 框架 / Unify external provider imports under a shared adapter framework

Problem / pain point / 问题

现在已经支持多种外部配置导入：

• Codex
• Claude Code
• Gemini CLI
• OpenCode

这已经很有价值，但 detect/import 仍然是逐个来源定制实现。随着来源继续增加，维护成本和漂移风险会越来越高。

We already support several external config sources, but each still owns a bespoke detect/import path.

Proposed solution / 方案

引入统一的 ExternalProviderAdapter 形状，让每个 adapter 负责：

• detect()
• import()
• warnings
• active provider / model
• secret material 只在 import 路径可见，不暴露到 renderer
• 可选 capability hints

This should preserve current safety guarantees while reducing duplicated plumbing.

Alternatives considered / 备选方案

• 继续每个 importer 单写
  • 重复逻辑会持续增长

Scope / 范围

Provider / model

Acceptance criteria / 验收标准

• 现有 external imports 可映射到统一 adapter contract
• detection 与 import 仍可分离，避免 secret 穿过 IPC
• renderer 侧 detection metadata 仍是 sanitized 的
• 不削弱现有 env-key / secret 安全约束
• 先迁移至少一个来源验证抽象是否合理

Likely touchpoints / 可能涉及

• apps/desktop/src/main/onboarding-ipc.ts
• apps/desktop/src/main/imports/*.ts
• packages/shared/src/detection.ts

[Sun-sunshine06]

Parent epic / 所属总 issue: #214

[github-actions]

感谢反馈，这个方向和当前代码现状是对齐的。

目前已经有一层共享的 external config detection contract，但 import / write path 仍然按来源分别实现，所以你提到的“detect/import 逐个来源定制实现”在当前代码里确实存在。

已确认的现状如下：

• preload / renderer 侧有统一的 detectExternalConfigs()，但导入入口仍是 4 个 source-specific IPC：Codex、Claude Code、Gemini、OpenCode。
• main 侧的 config:v1:detect-external-configs 会把 detection 结果投影成 sanitized metadata；例如 Codex detection 会明确剥离 apiKeyMap 和 envKeyMap，真正导入时再重新读源文件，所以明文 key 不会走 detection IPC。
• 不同来源的 import shape 目前并不统一：Codex / OpenCode 是多 provider 结构，Claude Code 是单 provider + apiKey，Gemini 是 found / blocked union。这说明现在还没有共享的 adapter contract。
• warnings、activeProvider、activeModel 这些信息已经分别出现在现有 detection/import 结构里；capability hints 我在当前代码里没有找到现成字段。

另外项目当前还是 v0.1.3 的早期快速迭代阶段，README 里的 roadmap 也把 provider / import 打磨列为当前方向，所以这类抽象收敛目前仍在进行中。

Relevant code:

• packages/shared/src/detection.ts:3 — detection IPC 的共享 contract，目前覆盖的是 sanitized detection metadata
• apps/desktop/src/preload/index.ts:327 — preload 暴露统一 detection + 4 个分开的 import IPC
• apps/desktop/src/main/onboarding-ipc.ts:1157 — 统一 detection IPC，内部并行读取 4 个外部配置源
• apps/desktop/src/main/onboarding-ipc.ts:1187 — Codex detection 明确剥离 apiKeyMap / envKeyMap，避免 secret 穿过 IPC
• apps/desktop/src/main/onboarding-ipc.ts:1257 — 4 个 source-specific import IPC 仍然独立存在
• apps/desktop/src/main/onboarding-ipc.ts:823 — runImportCodex()
• apps/desktop/src/main/onboarding-ipc.ts:889 — runImportClaudeCode()
• apps/desktop/src/main/onboarding-ipc.ts:946 — runImportGemini()
• apps/desktop/src/main/onboarding-ipc.ts:994 — runImportOpencode()
• apps/desktop/src/main/imports/codex-config.ts:17 — CodexImport 是多 provider + apiKeyMap / envKeyMap
• apps/desktop/src/main/imports/claude-code-config.ts:35 — ClaudeCodeImport 是单 provider + apiKey
• apps/desktop/src/main/imports/gemini-cli-config.ts:68 — GeminiImport 是 found / blocked union
• apps/desktop/src/main/imports/opencode-config.ts:164 — OpencodeImport 是多 provider + apiKeyMap
• README.zh-CN.md:248 — 当前仍是 v0.1.3，优先级会调整；导入能力也在 roadmap 中

---

open-codesign Bot

[github-actions]

感谢提交这个详细的 feature request！这个方向与项目的当前架构方向高度一致。

现状确认：

• 目前 packages/shared/src/detection.ts 定义了共享 detection contract，但 import 路径仍然是 source-specific IPC（4 个独立入口），与你的分析一致。
• CLAUDE.md / AGENTS.md 中明确提到“Reuse pi primitives first”——所有 LLM 调用通过 pi-ai，provider 通过 pi.registerProvider() 注册。这意味着未来统一 adapter 框架应当与 pi 的 provider 注册机制对齐，而不是再建一层抽象。
• 当前项目处于 v0.1.4（package.json），v0.2 计划向 agentic workspace 迁移，这期间 import 抽象收敛正是降低后续维护成本的关键一步。

建议考虑的方向：

• adapter contract 可以设计为 detect() → sanitized metadata（已有）和 import() → pi.registerProvider() 调用，直接复用 pi 的 provider registry，避免重复逻辑。
• 迁移第一个来源（如 OpenCode）验证抽象时，可以参考 packages/providers 中已有的 pi adapter 模式。

Relevant code:

• packages/shared/src/detection.ts:3 — 现有 detection contract
• apps/desktop/src/main/onboarding-ipc.ts:1157 — 统一 detection IPC
• apps/desktop/src/main/onboarding-ipc.ts:823-994 — 4 个 source-specific import IPC
• packages/providers/ — pi provider 注册示例

欢迎继续讨论具体 adapter 形状的细节！

---

Open-CoDesign Bot