paseo-req-kit 1.11.0 → 1.12.0-beta.2

package/engine/src/pipeline.ts

@@ -37,7 +37,7 @@ import { describeExternal, type IntegrationEvent, type Runner, syncIntegration }
 import { cardSlug, planAppendix, publishCard, readSource } from "./card.js";
 import { principlesSection, projectAdditions, type PromptLocations, readToolPrompt } from "./prompts.js";
 import type { AgentRuntime, ManagedService, ServiceTarget, StepAgent, WaitOutcome } from "./runtime.js";
-import { type CheckOutcome, type GateRun, type JointRepo, type PhaseName, type PipelineState, type RunPhases, type StepRecord, writeState } from "./state.js";
+import { type CheckOutcome, type GateRun, type JointRepo, type PhaseName, type PipelineState, type Recovery, type RunPhases, type StepRecord, type StopKind, writeState } from "./state.js";
 import { type PanelStep, STEPS, type StepDef, type StepId, stepKey, validateResult, VERIFY_PHASE_STEPS } from "./steps.js";
 
 export interface PipelineContext {
@@ -125,7 +125,38 @@ class StepFailure extends Error {
 }
 
 /** The step gave up on its agent while the agent may still be working (1.11). */
-class AgentLeftRunning extends StepFailure {}
+class AgentLeftRunning extends StepFailure {
+  constructor(
+    stepTitle: string,
+    message: string,
+    readonly timedOut: boolean,
+  ) {
+    super(stepTitle, message);
+  }
+}
+
+/** The agent's turn ended with an error status (1.12). */
+class AgentErrored extends StepFailure {}
+
+/** The agent did not write a valid result file, even after the reminders (1.12). */
+class ResultInvalid extends StepFailure {}
+
+/** Notes something the pipeline handled by itself (state.recoveries, the log). */
+function recover(ctx: PipelineContext, key: string, kind: Recovery["kind"], detail: string): void {
+  ctx.state.recoveries = [...(ctx.state.recoveries ?? []), { at: new Date().toISOString(), key, kind, detail: detail.slice(0, 300) }].slice(-200);
+  save(ctx);
+  ctx.log(`自动处理（${key}）：${detail}`);
+}
+
+/** Why a run stopped, as a code for the usage record (1.12). */
+function failureKind(error: unknown): StopKind {
+  if (error instanceof AgentLeftRunning) return error.timedOut ? "timeout" : "transient";
+  const message = (error as Error).message ?? "";
+  if (error instanceof StepFailure && isTransientError(message)) return "transient";
+  if (error instanceof AgentErrored) return "agent_error";
+  if (error instanceof ResultInvalid) return "invalid_result";
+  return "other";
+}
 
 /**
  * Errors that usually go away by themselves: provider rate limits and overload,
@@ -487,15 +518,31 @@ async function milestone(ctx: PipelineContext, id: string, text: string): Promis
   await notifyExternal(ctx, "milestone", text, { milestone: id });
 }
 
-async function waitForTurn(ctx: PipelineContext, agent: StepAgent, def: StepDef, agentTitle: string, deadline: number): Promise<AgentUsage | null> {
+/** A step's time limit; `extended` once it was given a second period (selfHeal). */
+interface Deadline {
+  at: number;
+  extended: boolean;
+  key: string;
+}
+
+async function waitForTurn(ctx: PipelineContext, agent: StepAgent, def: StepDef, agentTitle: string, deadline: Deadline): Promise<AgentUsage | null> {
   const notifiedPermissions = new Set<string>();
   let consecutiveErrors = 0;
   for (;;) {
-    const remaining = deadline - Date.now();
+    let remaining = deadline.at - Date.now();
+    if (remaining <= 0 && ctx.config.selfHeal && !deadline.extended) {
+      // Usually a big step, not a stuck one: the agent keeps its progress and gets as long again.
+      deadline.extended = true;
+      deadline.at = Date.now() + ctx.config.stepTimeoutMinutes[def.id] * 60_000;
+      remaining = deadline.at - Date.now();
+      recover(ctx, deadline.key, "extend_timeout", `超过 ${ctx.config.stepTimeoutMinutes[def.id]} 分钟仍未完成，agent 还在做，再给它同样长的时间`);
+    }
     if (remaining <= 0) {
+      const total = ctx.config.stepTimeoutMinutes[def.id] * (deadline.extended ? 2 : 1);
       throw new AgentLeftRunning(
         def.title,
-        `超过 ${ctx.config.stepTimeoutMinutes[def.id]} 分钟仍未完成。agent「${agentTitle}」还在运行，没有停止它；继续时会先看它的情况：做完了就用它的结果，还在做就接着等它，不会另起一个 agent 重复做。`,
+        `超过 ${total} 分钟仍未完成。agent「${agentTitle}」还在运行，没有停止它；继续时会先看它的情况：做完了就用它的结果，还在做就接着等它，不会另起一个 agent 重复做。`,
+        true,
       );
     }
     let outcome;
@@ -506,7 +553,7 @@ async function waitForTurn(ctx: PipelineContext, agent: StepAgent, def: StepDef,
       consecutiveErrors += 1;
       ctx.log(`等待 ${agentTitle} 时出错（第 ${consecutiveErrors} 次）：${(error as Error).message}`);
       if (consecutiveErrors >= 5) {
-        throw new AgentLeftRunning(def.title, `连续 ${consecutiveErrors} 次无法获取 agent 状态：${(error as Error).message}`);
+        throw new AgentLeftRunning(def.title, `连续 ${consecutiveErrors} 次无法获取 agent 状态：${(error as Error).message}`, false);
       }
       await ctx.sleep(Math.min(60_000, 5_000 * consecutiveErrors));
       continue;
@@ -517,7 +564,7 @@ async function waitForTurn(ctx: PipelineContext, agent: StepAgent, def: StepDef,
       case "timeout":
         continue;
       case "error":
-        throw new StepFailure(def.title, `agent 报告错误：${outcome.error ?? "未知错误"}`);
+        throw new AgentErrored(def.title, `agent 报告错误：${outcome.error ?? "未知错误"}`);
       case "permission": {
         const fresh = outcome.pendingPermissions.filter((p) => !notifiedPermissions.has(p.id));
         if (fresh.length > 0) {
@@ -562,31 +609,63 @@ async function runStep(
   extras: StepExtras = {},
 ): Promise<Record<string, unknown>> {
   const { attempts, backoffSeconds } = ctx.config.retry;
+  const key = extras.key ?? keyFor(stepKey(id, round), extras.target);
+  const fallback = ctx.config.agents.fallback ?? null;
+  let redone = false;
+  let usedFallback = false;
   for (let retry = 0; ; retry += 1) {
     try {
       return await runStepOnce(ctx, id, round, maxRounds, extras);
     } catch (error) {
       const message = (error as Error).message;
-      if (!(error instanceof StepFailure) || !isTransientError(message) || retry >= attempts) {
+      const transient = error instanceof StepFailure && isTransientError(message);
+      const healable = error instanceof AgentErrored || error instanceof ResultInvalid;
+      // 1.12: a step whose agent errored or wrote no valid result is redone once with a new
+      // agent; one that keeps hitting rate limits gets the fallback model, when there is one.
+      if (error instanceof StepFailure && ctx.config.selfHeal && !transient && healable && !redone) {
+        redone = true;
+        const switchModel = fallback !== null && !usedFallback && error instanceof AgentErrored;
+        if (switchModel) usedFallback = true;
+        recover(
+          ctx,
+          key,
+          switchModel ? "fallback" : "redo",
+          `${message.slice(0, 160)}；${switchModel ? "换备用模型" : "新开一个 agent"}重做这一步`,
+        );
+        extras = withRetryNote({ ...extras, ...(switchModel ? { profile: fallback } : {}) }, message);
+        continue;
+      }
+      if (error instanceof StepFailure && transient && retry >= attempts && fallback !== null && !usedFallback && !(error instanceof AgentLeftRunning)) {
+        usedFallback = true;
+        recover(ctx, key, "fallback", `重试 ${retry} 次后仍然${message.slice(0, 120)}；换备用模型继续这一步`);
+        extras = withRetryNote({ ...extras, profile: fallback }, message);
+        continue;
+      }
+      if (!(error instanceof StepFailure) || !transient || retry >= attempts) {
         if (error instanceof StepFailure && retry > 0) {
-          throw new StepFailure(error.stepTitle, `${message}（已自动重试 ${retry} 次）`);
+          throw new (error.constructor as typeof StepFailure)(error.stepTitle, `${message}（已自动重试 ${retry} 次）`);
         }
         throw error;
       }
       const wait = backoffSeconds.at(Math.min(retry, backoffSeconds.length - 1)) ?? 60;
-      ctx.log(`${error.stepTitle} 遇到临时错误：${message}。${wait} 秒后自动重试（第 ${retry + 1} 次，最多 ${attempts} 次）`);
+      recover(ctx, key, "retry", `遇到临时错误：${message.slice(0, 160)}。${wait} 秒后自动重试（第 ${retry + 1} 次，最多 ${attempts} 次）`);
       await ctx.sleep(wait * 1000);
-      extras = {
-        ...extras,
-        contextLines: [
-          ...(extras.contextLines ?? []).filter((l) => !l.startsWith("自动重试：")),
-          `自动重试：本步骤上一次因临时错误中断（${message.slice(0, 200)}）。工作区里可能留有上一次没做完的改动，先用 git status 和 git diff 查看，在此基础上继续，不要重复提交`,
-        ],
-      };
+      extras = withRetryNote(extras, message);
     }
   }
 }
 
+/** Tells the next agent of a step that an earlier one stopped part way. */
+function withRetryNote(extras: StepExtras, message: string): StepExtras {
+  return {
+    ...extras,
+    contextLines: [
+      ...(extras.contextLines ?? []).filter((l) => !l.startsWith("自动重试：")),
+      `自动重试：本步骤上一次中断了（${message.slice(0, 200)}）。工作区里可能留有上一次没做完的改动，先用 git status 和 git diff 查看，在此基础上继续，不要重复提交`,
+    ],
+  };
+}
+
 async function runStepOnce(
   ctx: PipelineContext,
   id: StepId,
@@ -671,7 +750,7 @@ async function runStepOnce(
     ctx.state.history.push(record);
     save(ctx);
 
-    const deadline = Date.now() + ctx.config.stepTimeoutMinutes[id] * 60_000;
+    const deadline: Deadline = { at: Date.now() + ctx.config.stepTimeoutMinutes[id] * 60_000, extended: false, key };
     record.usage = (await waitForTurn(ctx, agent, def, agentTitle, deadline)) ?? record.usage ?? null;
     let validation = readResultFile(resultAbs, def);
     while (!validation.ok && record.followUps < ctx.config.resultFollowUps) {
@@ -683,7 +762,7 @@ async function runStepOnce(
       validation = readResultFile(resultAbs, def);
     }
     if (!validation.ok) {
-      throw new StepFailure(def.title, `提醒 ${record.followUps} 次后仍没有得到有效的结果文件：${validation.error}`);
+      throw new ResultInvalid(def.title, `提醒 ${record.followUps} 次后仍没有得到有效的结果文件：${validation.error}`);
     }
 
     if (extras.gate) {
@@ -761,7 +840,7 @@ async function checkLeftover(
       last.result = validation.value;
       ctx.state.results[key] = validation.value;
       save(ctx);
-      ctx.log(`${key} 上一次的 agent ${last.agentId} 已经做完，沿用它的结果：${JSON.stringify(validation.value)}`);
+      recover(ctx, key, "reuse_result", `上一次的 agent ${last.agentId} 已经做完，沿用它的结果`);
       if (ctx.config.archiveStepAgents) await agent.archive().catch(() => undefined);
       return { done: validation.value };
     }
@@ -769,7 +848,10 @@ async function checkLeftover(
     return {};
   }
   if (status === "timeout" || status === "permission") {
-    if ((last.reattached ?? 0) < 1) return { agent, reattached: (last.reattached ?? 0) + 1 };
+    if ((last.reattached ?? 0) < 1) {
+      recover(ctx, key, "reattach", `上一次的 agent ${last.agentId} 还在做，接着等它，不另起一个`);
+      return { agent, reattached: (last.reattached ?? 0) + 1 };
+    }
     ctx.log(`${key} 上一次的 agent ${last.agentId} 已经等过两轮仍未完成，停止它并新建一个 agent`);
     await ctx.runtime
       .interruptAgent(last.agentId, "这一步已超时，流水线会另起一个 agent 重做。请立即停止当前工作，不要再修改任何文件，也不要写结果文件，直接结束。")
@@ -1023,6 +1105,26 @@ async function scheduleApprovalContinue(ctx: PipelineContext): Promise<string |
 }
 
 /** A Paseo schedule that has the chat continue the run later; returns the time as text, or null. */
+/** Rate limits and used-up subscriptions, as opposed to network trouble. */
+const QUOTA_ERROR = /rate.?limit|too many requests|\b429\b|quota|usage limit|额度|限流/i;
+
+/**
+ * 1.12: when a step stopped on rate limits and Paseo says when a used-up subscription window
+ * resets, the time to continue (5 minutes after the reset, within 24 hours); null otherwise.
+ */
+async function quotaResetTime(ctx: PipelineContext, reason: string): Promise<Date | null> {
+  if (!QUOTA_ERROR.test(reason)) return null;
+  const profiles = [ctx.config.agents.builder, ctx.config.agents.reviewer, ...(ctx.config.agents.fallback ? [ctx.config.agents.fallback] : [])];
+  const providers = [...new Set(profiles.map((p) => (p.provider ?? "").split("/")[0]).filter(Boolean))];
+  const quotas = await ctx.runtime.providerQuota(providers).catch(() => null);
+  const now = Date.now();
+  const resets = (quotas ?? [])
+    .filter((q) => q.resetsAt && ((q.usedPct !== null && q.usedPct >= 95) || q.tone === "danger"))
+    .map((q) => new Date(q.resetsAt!).getTime())
+    .filter((t) => t > now && t < now + 24 * 3600_000);
+  return resets.length === 0 ? null : new Date(Math.max(...resets) + 5 * 60_000);
+}
+
 async function scheduleAutoResume(ctx: PipelineContext, reason: string): Promise<string | null> {
   const minutes = ctx.config.autoResumeMinutes;
   const origin = ctx.state.originAgentId;
@@ -1032,7 +1134,8 @@ async function scheduleAutoResume(ctx: PipelineContext, reason: string): Promise
     ctx.log(`这次尝试已经自动继续过 ${used} 次，不再预约`);
     return null;
   }
-  const at = new Date(Date.now() + minutes * 60_000);
+  const reset = await quotaResetTime(ctx, reason);
+  const at = reset ?? new Date(Date.now() + minutes * 60_000);
   try {
     const id = await ctx.runtime.scheduleMessage({
       agentId: origin,
@@ -1049,7 +1152,9 @@ async function scheduleAutoResume(ctx: PipelineContext, reason: string): Promise
     ctx.state.schedules = [...(ctx.state.schedules ?? []), { id, kind: "auto-resume", at: at.toISOString() }];
     ctx.state.autoResumes = { attempt: ctx.state.attempt, count: used + 1 };
     save(ctx);
-    ctx.log(`已预约 ${minutes} 分钟后自动继续（Paseo 定时任务 ${id}）`);
+    const when = at.toLocaleString("zh-CN", { hour12: false });
+    if (reset) recover(ctx, "pipeline", "quota_wait", `额度用完，Paseo 显示会恢复；已预约在 ${when} 自动继续（Paseo 定时任务 ${id}）`);
+    else recover(ctx, "pipeline", "auto_resume", `已预约 ${minutes} 分钟后自动继续（Paseo 定时任务 ${id}）`);
     return at.toLocaleString("zh-CN", { hour12: false, month: "numeric", day: "numeric", hour: "2-digit", minute: "2-digit" });
   } catch (error) {
     ctx.log(`预约自动继续失败：${(error as Error).message}`);
@@ -1080,7 +1185,7 @@ async function checkQuota(ctx: PipelineContext): Promise<void> {
     [
       "【需求开发流水线通知】这条消息来自后台流水线，不是用户发的。",
       `额度提醒：${items.join("；")}。`,
-      "流水线照常进行；额度用完时会遇到限流，流水线会自动等待重试，重试用完会中断，之后可以继续。如果希望等额度恢复后再开发，请转告用户，用户同意的话可以先暂停。",
+      `流水线照常进行；额度用完时会遇到限流，流水线会先重试${ctx.config.agents.fallback ? "、再换备用模型" : ""}，仍不行就预约在额度恢复后自动继续，不需要人处理。如果希望等额度恢复后再开发，请转告用户，用户同意的话可以先暂停，再预约在恢复时间开始。`,
     ].join("\n"),
   );
 }
@@ -1567,11 +1672,33 @@ async function assessmentPhase(ctx: PipelineContext): Promise<void> {
   for (let r = 1; r <= rounds.designReview; r++) {
     const review = await runReview(ctx, "design_review", r, rounds.designReview);
     if (review.verdict === "approved") break;
-    if (review.verdict === "blocked") throw new BusinessDecisionNeeded(review.questions as string[]);
+    if (review.verdict === "blocked") {
+      await answerFirst(ctx, review, r, rounds.designReview);
+      continue;
+    }
     await runStep(ctx, "design_revise", r, rounds.designReview);
   }
 }
 
+/**
+ * The review says only the requester can decide (1.12): the builder first answers what the
+ * code, the documents and the spec settle, in a revision of the design; what is left goes to
+ * the requester, each with a recommended answer.
+ */
+async function answerFirst(ctx: PipelineContext, review: Record<string, unknown>, round: number, maxRounds: number): Promise<void> {
+  const questions = (review.questions as string[]) ?? [];
+  if (!ctx.config.answerQuestionsFirst) throw new BusinessDecisionNeeded(questions);
+  const revised = await runStep(ctx, "design_revise", round, maxRounds, {
+    contextLines: [`审核结论：需要需求方决定（${questions.length} 个问题，见 design-review.md）。按本步骤说明中"审核要求需求方决定时"一节，先自己找答案`],
+  });
+  const left = Array.isArray(revised.business_questions) ? (revised.business_questions as string[]).map((q) => q.trim()).filter(Boolean) : [];
+  const answered = Math.max(0, questions.length - left.length);
+  if (answered > 0) {
+    recover(ctx, `design_revise-r${round}`, "self_answer", `方案审核提出的 ${questions.length} 个问题中，${answered} 个由 builder 从代码和文档中确定了答案${left.length > 0 ? `，${left.length} 个交给需求方` : "，不用等需求方"}`);
+  }
+  if (left.length > 0) throw new BusinessDecisionNeeded(left);
+}
+
 /** Develop phase: design → design review ⇄ revise → implement → code review ⇄ fix → handoff. Returns the design result. */
 async function developPhase(ctx: PipelineContext): Promise<Record<string, unknown>> {
   const rounds = ctx.config.profiles[ctx.state.profile].rounds;
@@ -1602,7 +1729,10 @@ async function developPhase(ctx: PipelineContext): Promise<Record<string, unknow
     const review = await runReview(ctx, "design_review", r, rounds.designReview);
     designRounds = r;
     if (review.verdict === "approved") break;
-    if (review.verdict === "blocked") throw new BusinessDecisionNeeded(review.questions as string[]);
+    if (review.verdict === "blocked") {
+      await answerFirst(ctx, review, r, rounds.designReview);
+      continue;
+    }
     // changes_required. The last round's revision goes straight to implementation;
     // the implementer reads both the review and the revision record.
     await runStep(ctx, "design_revise", r, rounds.designReview);
@@ -1876,6 +2006,7 @@ async function flow(ctx: PipelineContext): Promise<Record<string, unknown>> {
 export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome> {
   ctx.state.status = "running";
   ctx.state.stopReason = null;
+  ctx.state.stopKind = null;
   save(ctx);
   await integrate(ctx, phaseOf(ctx) === "verify" ? "verify" : "started");
   try {
@@ -1917,6 +2048,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
     if (error instanceof PhaseGate) {
       ctx.state.status = "phase_done";
       ctx.state.stopReason = null;
+      ctx.state.stopKind = "phase_gate";
       save(ctx);
       await stopManagedServices(ctx);
       const verifyAt = await scheduleVerifyStart(ctx);
@@ -1947,6 +2079,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
     if (error instanceof ApprovalNeeded) {
       ctx.state.status = "waiting_for_approval";
       ctx.state.stopReason = null;
+      ctx.state.stopKind = "approval";
       save(ctx);
       const autoContinueAt = await scheduleApprovalContinue(ctx);
       const reminderHours = await scheduleReminder(ctx, "approval");
@@ -1974,6 +2107,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
     if (error instanceof BusinessDecisionNeeded) {
       const reproduce = error.source === "reproduce";
       ctx.state.status = "waiting_for_business";
+      ctx.state.stopKind = reproduce ? "reproduce" : "business";
       ctx.state.stopReason = `${reproduce ? "没能复现缺陷，需要需求方补充信息" : "方案审核需要需求方决定"}：${error.questions.join("；")}`;
       save(ctx);
       const reminderHours = await scheduleReminder(ctx, error.questions);
@@ -1994,6 +2128,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
     const stepTitle = error instanceof StepFailure ? error.stepTitle : "流水线";
     ctx.state.status = "failed";
     ctx.state.stopReason = `${stepTitle}：${(error as Error).message}`;
+    ctx.state.stopKind = failureKind(error);
     save(ctx);
     const autoResumeAt =
       error instanceof StepFailure && isTransientError((error as Error).message) ? await scheduleAutoResume(ctx, (error as Error).message) : null;

package/engine/src/records.ts

@@ -165,6 +165,10 @@ export interface RunRecord {
     /** The report's verdict when the run completed (completed, completed_with_issues, not_completed). */
     outcome: string | null;
     stopReason: string | null;
+    /** 1.12: why the run stopped for a person, as a code (absent in older records). */
+    stopKind?: string | null;
+    /** 1.12: what the pipeline handled by itself during the run, by kind (absent in older records). */
+    recoveries?: Record<string, number>;
   };
   agents: { builder: string | null; reviewer: string | null };
   steps: StepUsageRecord[];
@@ -241,6 +245,10 @@ export function runRecord(input: {
       status: state.status,
       outcome: state.status === "completed" ? state.outcome : null,
       stopReason: state.stopReason,
+      stopKind: state.status === "completed" || state.status === "running" ? null : (state.stopKind ?? null),
+      recoveries: (state.recoveries ?? [])
+        .filter((r) => new Date(r.at).getTime() >= since)
+        .reduce<Record<string, number>>((m, r) => ({ ...m, [r.kind]: (m[r.kind] ?? 0) + 1 }), {}),
     },
     agents: input.agents,
     steps,

package/engine/src/state.ts

@@ -27,6 +27,32 @@ export interface RunPhases {
   defects: DefectHandling;
 }
 
+/**
+ * Why a run stopped for a person (1.12). Necessary decisions: approval (the plan), business
+ * (a question only the requester can answer), reproduce (a defect that could not be reproduced),
+ * phase_gate (development done, waiting for testing). The rest are interruptions.
+ */
+export type StopKind =
+  | "approval"
+  | "business"
+  | "reproduce"
+  | "phase_gate"
+  | "timeout"
+  | "agent_error"
+  | "invalid_result"
+  | "transient"
+  | "stopped"
+  | "process_exit"
+  | "other";
+
+/** Something the pipeline handled by itself (1.12). */
+export interface Recovery {
+  at: string;
+  key: string;
+  kind: "retry" | "reattach" | "reuse_result" | "extend_timeout" | "redo" | "fallback" | "auto_resume" | "quota_wait" | "self_answer";
+  detail: string;
+}
+
 export interface StepRecord {
   key: string;
   stepId: StepId;
@@ -69,6 +95,10 @@ export interface PipelineState {
   results: Record<string, Record<string, unknown>>;
   history: StepRecord[];
   stopReason: string | null;
+  /** 1.12: why the run stopped for a person, as a code (contracts/usage-record.md); null while running or done. */
+  stopKind?: StopKind | null;
+  /** 1.12: what the pipeline handled by itself instead of stopping (retries, waiting longer, a fallback model…). */
+  recoveries?: Recovery[];
   outcome: string | null;
   /** "quick" or "standard"; decides loop rounds and optional steps. */
   profile: ProfileName;

package/engine/src/stats.ts

@@ -109,6 +109,35 @@ function waitKind(status: string): WaitKind {
   return "other";
 }
 
+/** Why runs stopped for a person (1.12, state.stopKind). */
+export const STOP_LABELS: Record<string, string> = {
+  approval: "确认方案",
+  phase_gate: "研发完成，等待测试",
+  business: "方案审核的问题等需求方决定",
+  reproduce: "缺陷复现不了，等需求方补充",
+  timeout: "步骤超时",
+  agent_error: "agent 报错",
+  invalid_result: "结果文件无效",
+  transient: "限流、网络等临时错误（自动重试用完）",
+  stopped: "被手动停止",
+  process_exit: "后台进程意外退出",
+  other: "其他中断",
+};
+
+/** Stops that are the decisions people are meant to make; the rest are what 1.12 works to remove. */
+export const NECESSARY_STOPS = ["approval", "phase_gate"];
+
+/** The stop code of a run; older records (before 1.12) are inferred from the status. */
+export function stopKindOf(r: RunRecord): string | null {
+  if (r.run.stopKind !== undefined) return r.run.stopKind;
+  if (r.run.status === "waiting_for_approval") return "approval";
+  if (r.run.status === "waiting_for_business") return "business";
+  if (r.run.status === "phase_done") return "phase_gate";
+  if (r.run.status === "failed") return /手动停止|被 SIG/.test(r.run.stopReason ?? "") ? "stopped" : "other";
+  if (r.run.status === "running") return "process_exit";
+  return null;
+}
+
 /** Records of the same run seen twice (merged exports) count once. */
 export function dedupe(runs: RunRecord[]): RunRecord[] {
   const seen = new Map<string, RunRecord>();
@@ -208,6 +237,19 @@ export interface StatsSummary {
   waits: Array<{ kind: WaitKind; label: string; requirements: number; averageMinutes: number }>;
   usage: { agentMinutes: number; inputTokens: number | null; outputTokens: number | null; costUsd: number | null };
   byBuilder: Array<{ builder: string; requirements: number; averageReviewRounds: number | null; averageCostUsd: number | null }>;
+  /** 1.12: why the period's runs stopped for a person, most frequent first. */
+  stops: Array<{ kind: string; label: string; necessary: boolean; runs: number }>;
+  /** 1.12: how much went without a person. */
+  automation: {
+    /** Of the requirements that reached testing (or completion) in the period, the share with no stop other than the necessary ones. */
+    unattendedShare: number | null;
+    /** Problems the pipeline handled by itself in the period's runs, by kind. */
+    recovered: Record<string, number>;
+    /** Runs that ended in an interruption (not a necessary decision). */
+    interrupted: number;
+    /** recovered / (recovered + interrupted). */
+    autoRecoveryShare: number | null;
+  };
   /** Requirements that started from cards, by who asked for them (1.10); empty when there are none. */
   byRequester: Array<{ requester: string; requirements: number; completed: number; medianCycleHours: number | null }>;
   requirements: RequirementStats[];
@@ -257,6 +299,24 @@ export function summarizeRuns(all: RunRecord[], period: Period): StatsSummary {
   const requesters = new Map<string, RequirementStats[]>();
   for (const q of active) if (q.card) requesters.set(q.requester ?? "（未记录）", [...(requesters.get(q.requester ?? "（未记录）") ?? []), q]);
 
+  const stopCounts = count(periodRuns.flatMap((r) => (stopKindOf(r) ? [stopKindOf(r)!] : [])));
+  const recovered: Record<string, number> = {};
+  for (const r of periodRuns) for (const [k, v] of Object.entries(r.run.recoveries ?? {})) recovered[k] = (recovered[k] ?? 0) + v;
+  const recoveredTotal = Object.values(recovered).reduce((a, b) => a + b, 0);
+  const interrupted = periodRuns.filter((r) => {
+    const k = stopKindOf(r);
+    return k !== null && !NECESSARY_STOPS.includes(k) && k !== "business" && k !== "reproduce";
+  }).length;
+  const reachedTesting = active.filter((q) => q.status === "completed" || q.status === "phase_done");
+  const unattended = reachedTesting.filter((q) =>
+    runs
+      .filter((r) => r.requirement.key === q.key && r.requirement.project === q.project)
+      .every((r) => {
+        const k = stopKindOf(r);
+        return k === null || NECESSARY_STOPS.includes(k);
+      }),
+  );
+
   return {
     schema: 1,
     period: { from: period.from?.toISOString() ?? null, to: period.to?.toISOString() ?? null, label: period.label },
@@ -287,6 +347,15 @@ export function summarizeRuns(all: RunRecord[], period: Period): StatsSummary {
       averageReviewRounds: avg(qs.map((q) => q.reviewRounds)),
       averageCostUsd: avg(qs.flatMap((q) => (q.costUsd === null ? [] : [q.costUsd]))),
     })),
+    stops: Object.entries(stopCounts)
+      .map(([kind, n]) => ({ kind, label: STOP_LABELS[kind] ?? kind, necessary: NECESSARY_STOPS.includes(kind), runs: n }))
+      .sort((a, b) => b.runs - a.runs || a.kind.localeCompare(b.kind)),
+    automation: {
+      unattendedShare: reachedTesting.length === 0 ? null : Math.round((unattended.length / reachedTesting.length) * 100) / 100,
+      recovered,
+      interrupted,
+      autoRecoveryShare: recoveredTotal + interrupted === 0 ? null : Math.round((recoveredTotal / (recoveredTotal + interrupted)) * 100) / 100,
+    },
     byRequester: [...requesters.entries()]
       .map(([requester, qs]) => {
         const finished = qs.filter((q) => done.includes(q));
@@ -349,6 +418,27 @@ export function describeStats(s: StatsSummary): string {
     `- 需要缺陷修复的需求占比：${s.rework.withDefectRounds === null ? "无数据" : `${Math.round(s.rework.withDefectRounds * 100)}%`}`,
     `- 质量门：运行 ${s.rework.gateRuns} 次，其中发现新失败 ${s.rework.gateFailed} 次`,
   );
+  const RECOVERY_LABELS: Record<string, string> = {
+    retry: "临时错误重试",
+    reattach: "接着等还在做的 agent",
+    reuse_result: "沿用旧 agent 的结果",
+    extend_timeout: "超时后多等一轮",
+    redo: "新开 agent 重做",
+    fallback: "换备用模型",
+    auto_resume: "自动继续",
+    quota_wait: "等额度恢复后继续",
+  };
+  lines.push(
+    "",
+    "## 人工介入",
+    "",
+    `- 到达提测（或完成）的需求中，除了确认方案外没有停下等人的：${s.automation.unattendedShare === null ? "无数据" : `${Math.round(s.automation.unattendedShare * 100)}%`}`,
+    `- 自动处理的问题 ${Object.values(s.automation.recovered).reduce((a, b) => a + b, 0)} 次（${list(s.automation.recovered, RECOVERY_LABELS)}），中断等人 ${s.automation.interrupted} 次${s.automation.autoRecoveryShare === null ? "" : `，自动处理的比例 ${Math.round(s.automation.autoRecoveryShare * 100)}%`}`,
+  );
+  if (s.stops.length > 0) {
+    lines.push("", "| 停下等人的原因 | 次数 | 必要的决定 |", "| --- | --- | --- |");
+    for (const st of s.stops) lines.push(`| ${st.label} | ${st.runs} | ${st.necessary ? "是" : "否"} |`);
+  }
   if (s.waits.length > 0) {
     lines.push("", "## 等待", "", "| 等待 | 需求数 | 平均 |", "| --- | --- | --- |");
     for (const w of s.waits) lines.push(`| ${w.label} | ${w.requirements} | ${hours(w.averageMinutes)} |`);

package/engine/src/steps.ts

@@ -132,7 +132,10 @@ export const STEPS: Record<StepId, StepDef> = {
     title: "方案修订",
     role: "builder",
     promptFile: "04b-design-revise.md",
-    result: { required: done.required, optional: { slices: { kind: "string[]" }, files: { kind: "string[]" }, ui_change: { kind: "boolean" } } },
+    result: {
+      required: done.required,
+      optional: { slices: { kind: "string[]" }, files: { kind: "string[]" }, ui_change: { kind: "boolean" }, business_questions: { kind: "string[]" } },
+    },
   },
   implement: {
     id: "implement",

package/install.mjs

@@ -9,6 +9,7 @@
 //   node install.mjs --prune                 list old version directories that can be deleted
 //   node install.mjs --uninstall             remove the skills req-kit installed (keeps ~/.req-kit)
 //   node install.mjs --configure             configuration wizard: pick the agents from what Paseo offers
+//   node install.mjs --configure --auto      the same without questions: the recommended agents (1.12)
 //   node install.mjs --upgrade [version]     download a version (default: the newest) next to this one,
 //                                            install its dependencies and switch to it
 //   node install.mjs --latest                print the newest published version
@@ -47,6 +48,9 @@ const { values, positionals } = parseArgs({
   allowPositionals: true,
   options: {
     configure: { type: "boolean", default: false },
+    auto: { type: "boolean", default: false },
+    "catalog-json": { type: "boolean", default: false },
+    set: { type: "string" },
     upgrade: { type: "boolean", default: false },
     latest: { type: "boolean", default: false },
     from: { type: "string" },
@@ -844,7 +848,7 @@ function configureCommand() {
     console.error(`依赖未安装：在 ${KIT_ROOT} 中执行 npm install 后再运行配置向导。`);
     return 1;
   }
-  const result = spawnSync(process.execPath, [tsx, path.join(KIT_ROOT, "engine", "src", "configure.ts"), "--config", CONFIG], {
+  const result = spawnSync(process.execPath, [tsx, path.join(KIT_ROOT, "engine", "src", "configure.ts"), "--config", CONFIG, ...(values.auto ? ["--auto"] : []), ...(values["catalog-json"] ? ["--catalog-json"] : []), ...(values.set !== undefined ? ["--set", values.set] : [])], {
     stdio: "inherit",
     windowsHide: true,
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-req-kit",
-  "version": "1.11.0",
+  "version": "1.12.0-beta.2",
   "description": "req-kit: a requirement-development workflow for Paseo. /req aligns a requirement in chat; the engine runs design, implementation, review and verification as Paseo agents.",
   "type": "module",
   "license": "MIT",
@@ -31,7 +31,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --import ./engine/test/isolate.ts --test --test-concurrency=1 engine/test/*.test.ts test/*.test.ts",
+    "test": "node --import tsx --import ./engine/test/isolate.ts --test --test-concurrency=1 --test-timeout=300000 engine/test/*.test.ts test/*.test.ts",
     "smoke": "tsx engine/src/smoke-test.ts",
     "doctor": "node bin/req-doctor.mjs",
     "eval": "tsx engine/src/eval.ts",

package/paseo-plugin/OVERVIEW.md

@@ -2,6 +2,8 @@ req-kit 的需求在 Paseo 里的样子：本机所有项目的需求一页看
 
 需要人处理的时候，可以直接在这里确认方案、停止、继续或开始测试验证。这些操作和在终端运行 `req approve`、`req stop`、`req resume`、`req verify` 完全一样，流水线本身不受插件影响；不想让人在网页上操作时，在插件设置中打开"只读"。
 
+在插件设置的"模型"一页，可以从 Paseo 中已登录的 agent 里选择 builder、reviewer 和备用模型，保存到 req-kit 的本机配置，和在终端运行 `req configure` 一样。
+
 还有：侧边栏的"需求"（带待处理数）、每个工作区头部的"需求"按钮和面板、步骤 agent 输入框旁的"需求"按钮，以及使用统计（交付周期、返工、等待、用量）。
 
 需要这台 daemon 上安装 req-kit 1.9 或更新的版本，插件通过本机的 `req api` 读取需求；它不连接任何外部服务。用 `req plugin install` 安装和更新。

package/paseo-plugin/client/data.ts

@@ -1,7 +1,7 @@
 // Data hooks: every read is an RPC to the daemon side (req api), cached by React Query.
 import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { useRpc, useSettings } from "@getpaseo/plugin/client";
-import { fileRpc, listRpc, preferences, runRpc, statsRpc, statusRpc, versionRpc, type Action } from "../shared/contracts";
+import { fileRpc, listRpc, modelsRpc, preferences, runRpc, setAgentsRpc, statsRpc, statusRpc, versionRpc, type Action, type AgentProfileData } from "../shared/contracts";
 
 export function usePreferences(): { readOnly: boolean; refreshMs: number } {
   const settings = useSettings(preferences);
@@ -53,3 +53,17 @@ export function useAction() {
     onSettled: () => queries.invalidateQueries({ queryKey: ["req"] }),
   });
 }
+
+export function useModels() {
+  const models = useRpc(modelsRpc);
+  return useQuery({ queryKey: ["req", "models"], queryFn: () => models({}), retry: false });
+}
+
+export function useSetAgents() {
+  const set = useRpc(setAgentsRpc);
+  const queries = useQueryClient();
+  return useMutation({
+    mutationFn: (input: { builder: AgentProfileData; reviewer: AgentProfileData; fallback: AgentProfileData | null }) => set(input),
+    onSettled: () => queries.invalidateQueries({ queryKey: ["req", "models"] }),
+  });
+}