@zhushanwen/pi-subagents 0.0.1

package/src/core/model-resolver.ts

@@ -0,0 +1,206 @@
+// src/core/model-resolver.ts
+//
+// 5 级 fallback 模型解析链。runtime 层调此函数解析后传入 SessionRunner，
+// SessionRunner 不重复解析。
+
+/**
+ * ModelRegistry 的最小接口（duck-typed，测试可 mock）。
+ * 字段结构与 Pi SDK 的 ctx.modelRegistry 对齐（见 shared/types stub），
+ * 保证 `runtime.initSession({ modelRegistry: ctx.modelRegistry })` 类型兼容。
+ */
+export interface ModelRegistryLike {
+  /** 返回所有已配置的可用模型。 */
+  getAvailable(): ModelInfo[];
+  /** 按 (provider, modelId) 查找。 */
+  find(provider: string, modelId: string): ModelInfo | undefined;
+  /** 校验模型鉴权是否就绪。 */
+  hasConfiguredAuth(model: unknown): boolean;
+}
+
+/** 模型信息（getAvailable 返回元素 / find 返回值）。 */
+export interface ModelInfo {
+  id: string;
+  name: string;
+  provider: string;
+  reasoning: boolean;
+  thinkingLevelMap?: Record<string, unknown>;
+  contextWindow?: number;
+}
+
+/** agent .md frontmatter 解析结果。 */
+export interface AgentConfig {
+  /** agent 名（文件名 basename）。 */
+  name: string;
+  /** system prompt（markdown 正文）。 */
+  systemPrompt: string;
+  /** tool allowlist（三层过滤之一）。 */
+  tools?: string[];
+  /** 默认模型 override（"provider/modelId"）。 */
+  model?: string;
+  /** 默认 thinkingLevel override。 */
+  thinkingLevel?: string;
+  /** 默认 background 模式（true 时无显式 wait 走 background）。 */
+  defaultBackground?: boolean;
+}
+
+/** 解析结果（model 实例 + 生效的 thinkingLevel）。复用 ModelInfo 消除重复。 */
+export interface ResolvedModel {
+  model: ModelInfo;
+  thinkingLevel: string | undefined;
+}
+
+/** resolveModelForAgent 的入参。 */
+export interface ResolveModelArgs {
+  agentName: string;
+  agentConfig: AgentConfig | undefined;
+  /** agent 推断出的 category。 */
+  category: string;
+  globalConfig: { categories: Record<string, { model: string; thinkingLevel?: string }>; fallback: { model: string; thinkingLevel?: string } };
+  sessionState: { categoryModels: Record<string, { model: string; thinkingLevel?: string }>; agentModels: Record<string, { model: string; thinkingLevel?: string }> };
+  modelRegistry: ModelRegistryLike;
+  /** 用户显式 override（tool 参数）。最高优先级。 */
+  paramOverride?: { model?: string; thinkingLevel?: string };
+}
+
+// ============================================================
+// 常量
+// ============================================================
+
+/** thinking level 支持顺序（低→高），用于 clamp 到 model 可用级别。 */
+const THINKING_ORDER = ["off", "minimal", "low", "medium", "high", "xhigh"] as const;
+
+/** 解析失败时错误信息列出的可用模型上限（防超长错误信息）。 */
+const MODEL_LIST_LIMIT = 20;
+
+/** agent 名 → category 的推断规则（按优先级，命中即返回）。 */
+const NAME_INFERENCE: ReadonlyArray<{ pattern: RegExp; category: string }> = [
+  { pattern: /cod|review|fix|refactor|implement|develop/i, category: "coding" },
+  { pattern: /research|search|investigat|scout|explore/i, category: "research" },
+  { pattern: /test|qa|lint|valid/i, category: "testing" },
+  { pattern: /plan|architect|design|strateg/i, category: "planning" },
+  { pattern: /vision|image|ocr|visual/i, category: "vision" },
+];
+
+/** 候选链条目：modelStr + 该级对应的 thinkingLevel。 */
+interface ModelCandidate {
+  modelStr: string;
+  thinkingLevel?: string;
+}
+
+/**
+ * 5 级 fallback 解析：
+ *
+ *   ╔═══════════════════════════════════════════════════════════════╗
+//   ║  优先级（高→低）:                                              ║
+//   ║    1. paramOverride.model      （用户显式指定，tool 参数）      ║
+//   ║    2. agent.model              （agent .md frontmatter）        ║
+//   ║    3. sessionState.agentModels （/subagents config 临时覆盖）   ║
+//   ║    4. sessionState.categoryModels + category                   ║
+//   ║    5. globalConfig.fallback    （兜底，保证总有一个 model）      ║
+//   ║                                                                ║
+//   ║  thinkingLevel 同链路解析（无指定时用 model 默认或 undefined）  ║
+//   ║  解析失败（前 4 级全不可用）→ 抛错（让 Runtime 决定静默/失败）  ║
+//   ╚═══════════════════════════════════════════════════════════════╝
+ */
+export function resolveModelForAgent(args: ResolveModelArgs): ResolvedModel {
+  const { agentConfig, agentName, category, globalConfig, sessionState, modelRegistry } = args;
+
+  // 组装候选链（按优先级）
+  const candidates: ModelCandidate[] = [];
+  if (args.paramOverride?.model) {
+    candidates.push({ modelStr: args.paramOverride.model, thinkingLevel: args.paramOverride.thinkingLevel });
+  }
+  if (agentConfig?.model) {
+    candidates.push({ modelStr: agentConfig.model, thinkingLevel: agentConfig.thinkingLevel });
+  }
+  const agentOverride = sessionState.agentModels[agentName];
+  if (agentOverride) {
+    candidates.push({ modelStr: agentOverride.model, thinkingLevel: agentOverride.thinkingLevel });
+  }
+  const categoryModel = sessionState.categoryModels[category] ?? globalConfig.categories[category];
+  if (categoryModel) {
+    candidates.push({ modelStr: categoryModel.model, thinkingLevel: categoryModel.thinkingLevel });
+  }
+  candidates.push({ modelStr: globalConfig.fallback.model, thinkingLevel: globalConfig.fallback.thinkingLevel });
+
+  const tried: string[] = [];
+  for (const candidate of candidates) {
+    const model = lookupModel(candidate.modelStr, modelRegistry);
+    if (!model || !modelRegistry.hasConfiguredAuth(model)) {
+      tried.push(candidate.modelStr);
+      continue;
+    }
+    return {
+      model,
+      thinkingLevel: resolveThinkingLevel(model, candidate.thinkingLevel),
+    };
+  }
+
+  // 所有候选失败 → 列出可用模型辅助调试
+  const available = modelRegistry.getAvailable().map((m) => `${m.provider}/${m.id}`);
+  throw new Error(
+    `No available model for agent "${agentName}". Tried: ${tried.join(", ") || "(none)"}.` +
+      (available.length > 0
+        ? `\nAvailable models:\n  ${available.slice(0, MODEL_LIST_LIMIT).join("\n  ")}`
+        : ""),
+  );
+}
+
+/** 解析 "provider/modelId"（modelId 可含 /，取第一个 / 分割）并查 registry。 */
+function lookupModel(modelStr: string, registry: ModelRegistryLike): ModelInfo | undefined {
+  const idx = modelStr.indexOf("/");
+  if (idx <= 0) return undefined;
+  return registry.find(modelStr.slice(0, idx), modelStr.slice(idx + 1));
+}
+
+/**
+ * 从 model.thinkingLevelMap 提取可用级别，clamp 到最高可用。
+ * model.reasoning === false → undefined（不支持 thinking）
+ */
+function resolveThinkingLevel(
+  model: { reasoning: boolean; thinkingLevelMap?: Record<string, unknown> },
+  requested?: string,
+): string | undefined {
+  const levels = availableThinkingLevels(model);
+  if (levels.length === 0) return model.reasoning ? requested : undefined;
+  if (requested && levels.includes(requested)) return requested;
+  // requested 不可用 → 降级到最高可用
+  return levels[levels.length - 1];
+}
+
+/**
+ * 列出 model 实际支持的 thinking level（升序）。
+ *
+ *   - model.reasoning === false → [] （不支持 thinking）
+ *   - 无 thinkingLevelMap → [] （无级别信息，调用方按需透传）
+ *   - 有 map → THINKING_ORDER 中 map[lvl] != null 的子集（保留升序）
+ *
+ * confirm 组件 / config-wizard 用它渲染「该模型可选的 thinking 级别」菜单，
+ * 取代写死的全集 THINKING_LEVELS（不同 model 支持的级别不同）。
+ */
+export function availableThinkingLevels(
+  model: { reasoning: boolean; thinkingLevelMap?: Record<string, unknown> },
+): readonly string[] {
+  if (!model.reasoning) return [];
+  const map = model.thinkingLevelMap;
+  if (!map) return [];
+  return THINKING_ORDER.filter((lvl) => map[lvl] != null);
+}
+
+/** 从 agentName + config 推断 category（agentCategoryOverrides 优先）。 */
+export function inferCategory(
+  agentName: string,
+  agentConfig: AgentConfig | undefined,
+  overrides: Record<string, string>,
+  defaultCategory: string,
+): string {
+  // 1. 显式 override 命中
+  if (overrides[agentName]) return overrides[agentName];
+  // 2. agent 名前缀/约定推断
+  for (const rule of NAME_INFERENCE) {
+    if (rule.pattern.test(agentName)) return rule.category;
+  }
+  // 3. fallback
+  void agentConfig;
+  return defaultCategory;
+}

package/src/core/output-collector.ts

@@ -0,0 +1,118 @@
+// src/core/output-collector.ts
+//
+// 结果收集器（逆向：BuiltSession + CollectResultArgs → AgentResult）。
+// 与 session-factory 对称：factory 造 bundle，collector 拆 bundle。
+//
+// 基础层模块：依赖 event-bridge（读累积器）+ session-factory（AgentSessionLike）+ types。
+// 字段来源契约见 docs/subagents/session-runner.md §4。
+
+import type { AgentResult, AgentUsage, AgentUsageTotal, ToolCall } from "../types.ts";
+import type { EventBridge } from "./event-bridge.ts";
+import type { AgentSessionLike } from "./session-factory.ts";
+
+// ============================================================
+// Result 收集
+// ============================================================
+
+/** collectResult 的入参（字段来源明确，避免多处拼装）。 */
+export interface CollectResultArgs {
+  startTime: number;
+  success: boolean;
+  error: string | undefined;
+  sessionId: string;
+  sessionFile: string | undefined;
+  turns: number;
+  usage: AgentUsageTotal | undefined;
+  toolCalls: ToolCall[];
+}
+
+/** structured-output tool 名（与 structured-output 扩展 TOOL_NAME 一致，见 session-runner.ts）。 */
+const STRUCTURED_OUTPUT_TOOL = "structured-output";
+
+/**
+ * 从 toolCalls 提取 structured-output 的 result.details（schema 模式产出）。
+ * schema enforcement 保证 agent 调过该 tool（漏调会 steer 重试）；这里只做逆向提取。
+ * 未调或无 details 返回 undefined。
+ *
+ * 导出以便直接单测（与 toUsageTotal/collectResponseText 一致，三者同属决定
+ * AgentResult 字段来源的纯函数契约）。
+ */
+export function extractParsedOutput(toolCalls: ToolCall[]): unknown {
+  for (let i = toolCalls.length - 1; i >= 0; i--) {
+    const tc = toolCalls[i]!;
+    if (tc.toolName === STRUCTURED_OUTPUT_TOOL && tc.result?.details !== undefined) {
+      return tc.result.details;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 从 session + bridge 组装 AgentResult。每个字段来源单一：
+ *   text ← session.messages 最后一条 assistant message 的 text 部分（倒序找）
+ *   turns ← bridge.turnCount
+ *   usage ← bridge.usage（全零则 undefined）
+ *   toolCalls ← bridge.toolCalls
+ *   parsedOutput ← toolCalls 找 toolName==="structured-output" 的 result.details
+ *
+ * success 双来源判定：
+ *   ① session.prompt() 抛错 → args.success=false
+ *   ② prompt 成功但 bridge.lastError 非空（message_end stopReason=error）→ success=false
+ */
+export function collectResult(
+  session: AgentSessionLike,
+  bridge: EventBridge,
+  args: CollectResultArgs,
+): AgentResult {
+  void bridge; // bridge 累积器已在调用方（run）经 toUsageTotal/slice 提取后传入 args
+  return {
+    text: collectResponseText(session.messages),
+    turns: args.turns,
+    durationMs: Date.now() - args.startTime,
+    success: args.success,
+    error: args.error,
+    sessionId: args.sessionId,
+    toolCalls: args.toolCalls,
+    usage: args.usage,
+    sessionFile: args.sessionFile,
+    parsedOutput: extractParsedOutput(args.toolCalls),
+  };
+}
+
+/** 从 session.messages 最后一条 assistant message 提取文本。 */
+export function collectResponseText(
+  messages: ReadonlyArray<{
+    role: string;
+    content?: ReadonlyArray<{ type: string; text?: string }>;
+  }>,
+): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const msg = messages[i];
+    if (msg.role !== "assistant") continue;
+    const parts = msg.content ?? [];
+    let text = "";
+    for (const part of parts) {
+      if (part.type === "text" && typeof part.text === "string") {
+        text += part.text;
+      }
+    }
+    return text;
+  }
+  return "";
+}
+
+// ============================================================
+// Usage 纯 helper
+// ============================================================
+
+/**
+ * AgentUsage & {cost} → AgentUsageTotal（全零则 undefined）。
+ * 纯函数：run 在 collectResult 前用它规整 bridge.usage。
+ */
+export function toUsageTotal(
+  usage: AgentUsage & { cost: number },
+): AgentUsageTotal | undefined {
+  const total = usage.input + usage.output + usage.cacheRead + usage.cacheWrite;
+  if (total === 0 && usage.cost === 0) return undefined;
+  return { ...usage, total };
+}

package/src/core/path-encoding.ts

@@ -0,0 +1,16 @@
+// src/core/path-encoding.ts
+//
+// cwd → 安全目录名的编码逻辑。Core 叶子原语（零依赖）。
+//
+// 被 session-factory（subagent session 持久化目录）与 history-store（history.jsonl
+// 目录）共用——两处需要相同的编码，否则同一 cwd 会落到两个不同目录。
+// 历史上两文件各有一份逐字相同的副本，此文件消除该重复。
+
+/**
+ * cwd → 安全目录名。复用 Pi SDK getDefaultSessionDir 的编码逻辑：
+ * 去开头单个分隔符，全量替换剩余分隔符/冒号为 `-`，首尾补 `--`。
+ * 例：`/Users/x/proj` → `--Users-x-proj--`。
+ */
+export function encodeCwd(cwd: string): string {
+  return "--" + cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-") + "--";
+}