feat(contracts,db): Pi upstream contracts and pi_upstream table

- contracts/pi.ts: 41 builtin provider ids + openai-compatible + fake, auth kinds,
  upstream row/view/create/update, provider capability table (oauth modes, termsNote),
  test/models/oauth start/complete schemas
- settings.pi gains defaultUpstreamId; legacy single-upstream fields kept for fallback
- api.ts: /pi/providers, /pi/upstreams CRUD, test, models, oauth start/complete/logout
  (writes and login are console-session only)
- migration 0027: pi_upstream, agent_run.upstream_id, one-time conversion of saved
  legacy settings.pi into a default upstream

Co-Authored-By: Claude Opus 5.5 <[email protected]>

packages/contracts/src/settings.ts

@@ -50,11 +50,23 @@ export type RetentionSettings = z.infer<typeof RetentionSettings>;
 export const ThinkingLevel = z.enum(["off", "minimal", "low", "medium", "high", "xhigh"]);
 export type ThinkingLevel = z.infer<typeof ThinkingLevel>;
 
-/** Pi Agent 设置(REQ §10.5):上游/模型/思考档位/上下文预算/压缩/子代理;密钥只存 secret 引用 */
+/**
+ * Pi Agent 设置(REQ §10.5)。W7-A 起上游改为 pi_upstream 表(多上游共存,见 contracts/pi.ts 与 /pi/upstreams),
+ * 这里只留默认上游与运行预算(上下文预算/压缩/子代理)。
+ *
+ * provider / baseUrl / model / thinkingLevel / apiKeySecretRef 是 v0.1 的旧字段:0027 迁移把已保存的旧值转成一条上游
+ * 并设为默认;之后仅在 defaultUpstreamId 为 null 时作为兼容回退(provider = "fake" 的 e2e/演示也走这里)。
+ */
 export const PiSettings = z.object({
+  /** 缺省上游(runAgent 未指定 upstreamId 时使用);null = 回退到旧字段 */
+  defaultUpstreamId: Id.nullable(),
+  /** @deprecated 旧字段,见上 */
   provider: z.string().min(1),
+  /** @deprecated */
   baseUrl: z.url().nullable(),
+  /** @deprecated */
   model: z.string().min(1).nullable(),
+  /** @deprecated 上游级 thinkingLevel 见 pi_upstream */
   thinkingLevel: ThinkingLevel,
   /** 上下文预算(token) */
   contextBudget: z.number().int().min(4096).max(2_000_000),
@@ -64,13 +76,14 @@ export const PiSettings = z.object({
     thresholdRatio: z.number().min(0.3).max(0.95),
   }),
   subagentsEnabled: z.boolean(),
+  /** @deprecated */
   apiKeySecretRef: Id.nullable(),
 });
 export type PiSettings = z.infer<typeof PiSettings>;
 
 /**
  * Agent 运行参数(REQ §10.5、§10.7):单次运行预算、后台自动调查、fake 演示脚本。
- * 上游/模型/思考档位在 pi 分组;pi.provider = "fake" 时使用脚本化假模型(不联网,演示与 e2e 用)。
+ * 上游/模型/思考档位在 pi_upstream(见 contracts/pi.ts);provider = "fake" 的上游使用脚本化假模型(不联网,演示与 e2e 用)。
  */
 export const AgentRuntimeSettings = z.object({
   /** 识别歧义 / 下载失败诊断等待处理事项创建时,自动发起有界调查 */
@@ -161,6 +174,7 @@ export const DEFAULT_SETTINGS: GlobalSettings = {
   organize: { defaultMode: "copy", allowCrossVolumeMove: true },
   retention: { seedRetentionDays: 7, logRetentionDays: 180 },
   pi: {
+    defaultUpstreamId: null,
     provider: "anthropic",
     baseUrl: null,
     model: null,
@@ -201,7 +215,8 @@ export const GlobalSettingsUpdate = z.object({
   cache: CacheShape.partial().optional(),
   organize: OrganizeSettings.partial().optional(),
   retention: RetentionSettings.partial().optional(),
-  pi: PiSettings.omit({ apiKeySecretRef: true })
+  /** defaultUpstreamId 只能经 /pi/upstreams(makeDefault)修改,保证指向存在的上游 */
+  pi: PiSettings.omit({ apiKeySecretRef: true, defaultUpstreamId: true })
     .partial()
     .extend({
       compaction: PiSettings.shape.compaction.partial().optional(),