paseo-req-kit 1.11.0-beta.1 → 1.11.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 [docs/guide/安装与升级.md](docs/guide/安装与升级.md)。
 
+## 1.11.0
+
+稳定版：包含 1.10 的"从卡片开始的需求"和 1.11 的接单器（详见下面的 beta 记录），并修正步骤超时后会重复开 agent 的问题。
+
+### 使用者会看到的变化
+
+- **从卡片开始的需求**（1.10）：`req start --from <系统>:<卡号>` 读卡片、建需求会话；卡片描述末尾的 AI 区和需求方回复区代替对话；按子系统自动选仓库；工厂模式下研发完成后可以推送 `req/` 分支；统计按需求方汇总。
+- **接单器**（1.11）：`req factory` 定时接标题带 `[AI]`/`【AI】` 的新卡片，并把需求方的回复转给需求会话。
+- **修正：步骤超时后不再重复开 agent**。以前超时只判定失败、不看 agent 实际状态，继续时会新建一个 agent，而旧的仍在运行，两个 agent 同时改同一批文件、在同一个工作区提交、写同一个结果文件，需要手动停止旧的。现在继续（`--resume`、自动重试）时先看上一次的 agent：做完了就用它的结果；还在做就接着等它一轮；第二次仍超时才停止它，再新建。连续读不到 agent 状态时同样处理。
+
+### 升级须知
+
+- 从 1.9 升级：先看 1.10.0-beta.1 至 1.11.0-beta.1 的升级须知（对接配置的 `query`、`describe`、`list`，项目配置的 `cardSource`，本机或团队配置的 `push`、`factory`）。不用卡片的项目不需要改任何配置。
+- 状态文件的步骤记录新增 `leftRunning`、`reattached` 两项，旧状态文件照常可用。
+
 ## 1.11.0-beta.1
 
 接单器：一台共享研发机器自动接卡片、转达回复，需求方只在卡片上操作。

package/docs/guide//351/241/271/347/233/256/345/256/232/345/210/266/344/270/216/350/277/220/350/241/214/350/247/204/345/210/231.md

@@ -471,7 +471,7 @@ Paseo 自带的 `/paseo-advisor`、`/paseo-committee` 等编排 skill 也可以
 
 **结果文件**：每步必须写一个 JSON 结果文件，流水线只看它，不看 agent 的回复文字。文件缺失或格式不对时，会在同一个会话里提醒 agent 补写，最多 2 次，仍不对则判定该步骤失败。
 
-**等待与超时**：每步有总时限（`stepTimeoutMinutes`），超时判定失败（agent 可能仍在运行，可在 Paseo 中查看）。等待被拆成每段 10 分钟，连接断开时自动重试。agent 等待权限批准时，同一个请求只通知一次，然后继续等待。
+**等待与超时**：每步有总时限（`stepTimeoutMinutes`），超时判定失败，但不停止 agent。继续（`--resume`、自动重试）时先看这一步上一次的 agent：已经做完、结果文件有效就直接用它的结果；还在做就接着等它一轮；第二次仍超时才停止它、另起一个 agent。同一步不会有两个 agent 同时在做（它们会改同样的文件、在同一个工作区提交、写同一个结果文件）。连续读不到 agent 状态时同样处理。等待被拆成每段 10 分钟，连接断开时自动重试。agent 等待权限批准时，同一个请求只通知一次，然后继续等待。
 
 **临时错误自动重试**：步骤因限流（429）、服务暂时不可用（502/503/504/529、overloaded）、网络中断等临时错误失败时，等待后用新的 agent 重做这一步，并告诉它工作区里可能留有上一次没做完的改动。默认最多重试 2 次，分别等 1 分钟和 5 分钟：
 

package/engine/src/paseo-runtime.ts

@@ -199,6 +199,9 @@ export function createRuntimeWithClient(
     async notifyAgent(agentId, text) {
       await client.agents.ref(agentId).send(text, { activeTurnBehavior: "steer" });
     },
+    attachAgent(agentId) {
+      return wrap(client.agents.ref(agentId));
+    },
     async interruptAgent(agentId, text) {
       await client.agents.ref(agentId).send(text, { activeTurnBehavior: "interrupt" });
     },

package/engine/src/pipeline.ts

@@ -36,7 +36,7 @@ import { dispatchNotifiers, type NotifierEventType } from "./notifiers.js";
 import { describeExternal, type IntegrationEvent, type Runner, syncIntegration } from "./integrations.js";
 import { cardSlug, planAppendix, publishCard, readSource } from "./card.js";
 import { principlesSection, projectAdditions, type PromptLocations, readToolPrompt } from "./prompts.js";
-import type { AgentRuntime, ManagedService, ServiceTarget, StepAgent } from "./runtime.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 PanelStep, STEPS, type StepDef, type StepId, stepKey, validateResult, VERIFY_PHASE_STEPS } from "./steps.js";
 
@@ -124,6 +124,9 @@ class StepFailure extends Error {
   }
 }
 
+/** The step gave up on its agent while the agent may still be working (1.11). */
+class AgentLeftRunning extends StepFailure {}
+
 /**
  * Errors that usually go away by themselves: provider rate limits and overload,
  * dropped connections, a restarting daemon. A step that fails this way is started
@@ -490,9 +493,9 @@ async function waitForTurn(ctx: PipelineContext, agent: StepAgent, def: StepDef,
   for (;;) {
     const remaining = deadline - Date.now();
     if (remaining <= 0) {
-      throw new StepFailure(
+      throw new AgentLeftRunning(
         def.title,
-        `超过 ${ctx.config.stepTimeoutMinutes[def.id]} 分钟仍未完成。该 agent 可能仍在运行，可以在 Paseo 中查看「${agentTitle}」。`,
+        `超过 ${ctx.config.stepTimeoutMinutes[def.id]} 分钟仍未完成。agent「${agentTitle}」还在运行，没有停止它；继续时会先看它的情况：做完了就用它的结果，还在做就接着等它，不会另起一个 agent 重复做。`,
       );
     }
     let outcome;
@@ -503,7 +506,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 StepFailure(def.title, `连续 ${consecutiveErrors} 次无法获取 agent 状态：${(error as Error).message}`);
+        throw new AgentLeftRunning(def.title, `连续 ${consecutiveErrors} 次无法获取 agent 状态：${(error as Error).message}`);
       }
       await ctx.sleep(Math.min(60_000, 5_000 * consecutiveErrors));
       continue;
@@ -604,7 +607,11 @@ async function runStepOnce(
   const resultRel = `${ctx.featureDir}/.pipeline/results/${key}.json`;
   const resultAbs = path.join(stepRepo, resultRel);
   fs.mkdirSync(path.dirname(resultAbs), { recursive: true });
-  fs.rmSync(resultAbs, { force: true });
+
+  // An earlier run of this step may have left its agent working: use it, never run a second one.
+  const leftover = await checkLeftover(ctx, key, def, resultAbs);
+  if (leftover.done) return leftover.done;
+  if (!leftover.agent) fs.rmSync(resultAbs, { force: true });
 
   // Services, the browser and the deployed environment belong to the steps in this repository.
   const managed = target
@@ -638,10 +645,14 @@ async function runStepOnce(
     error: null,
     phase: phaseOf(ctx),
   };
-  ctx.log(`开始 ${key}（${def.title}）`);
+  if (leftover.agent) {
+    record.agentId = leftover.agent.id;
+    record.reattached = leftover.reattached;
+  }
+  ctx.log(leftover.agent ? `继续等待 ${key}（${def.title}）上一次的 agent ${leftover.agent.id}` : `开始 ${key}（${def.title}）`);
 
   try {
-    const agent = await ctx.runtime.startAgent({
+    const agent = leftover.agent ?? await ctx.runtime.startAgent({
       role: def.role,
       title: agentTitle,
       prompt: buildPrompt(ctx, def, round, maxRounds, resultRel, extras),
@@ -699,6 +710,7 @@ async function runStepOnce(
     record.outcome = "failed";
     record.endedAt = new Date().toISOString();
     record.error = (error as Error).message;
+    if (error instanceof AgentLeftRunning) record.leftRunning = true;
     if (!ctx.state.history.includes(record)) ctx.state.history.push(record);
     save(ctx);
     if (error instanceof StepFailure) throw error;
@@ -706,6 +718,69 @@ async function runStepOnce(
   }
 }
 
+/**
+ * Before a step starts an agent, looks at the agent an earlier run of the same step left
+ * working (a timeout, unreadable status, or a pipeline process that died mid-step):
+ * - it has finished and written a valid result: that result is the step's result;
+ * - it is still working: the step waits for it again (once); the second time it is stopped
+ *   and a new agent starts, so a stuck agent does not hold the step forever;
+ * - it cannot be reached, or finished without a valid result: a new agent starts.
+ * Two agents on one step would edit the same files, commit in the same worktree and write
+ * the same result file, so a new one never starts while the old one may be working.
+ */
+async function checkLeftover(
+  ctx: PipelineContext,
+  key: string,
+  def: StepDef,
+  resultAbs: string,
+): Promise<{ done?: Record<string, unknown>; agent?: StepAgent; reattached?: number }> {
+  const last = [...ctx.state.history].reverse().find((h) => h.key === key);
+  if (!last?.agentId || last.outcome === "completed") return {};
+  if (last.outcome !== "running" && !last.leftRunning) return {};
+  last.leftRunning = false;
+  if (last.outcome === "running") {
+    last.outcome = "failed";
+    last.endedAt = new Date().toISOString();
+    last.error ??= "流水线进程在这一步运行时退出";
+  }
+  save(ctx);
+  const agent = ctx.runtime.attachAgent(last.agentId);
+  let status: WaitOutcome["status"] | "unreachable";
+  try {
+    status = (await agent.wait(Math.min(5_000, ctx.config.waitChunkSeconds * 1000))).status;
+  } catch (error) {
+    ctx.log(`无法读取 ${key} 上一次的 agent ${last.agentId} 的状态（${(error as Error).message}），新建一个 agent`);
+    status = "unreachable";
+  }
+  if (status === "idle") {
+    const validation = readResultFile(resultAbs, def);
+    if (validation.ok) {
+      last.outcome = "completed";
+      last.endedAt = new Date().toISOString();
+      last.error = null;
+      last.result = validation.value;
+      ctx.state.results[key] = validation.value;
+      save(ctx);
+      ctx.log(`${key} 上一次的 agent ${last.agentId} 已经做完，沿用它的结果：${JSON.stringify(validation.value)}`);
+      if (ctx.config.archiveStepAgents) await agent.archive().catch(() => undefined);
+      return { done: validation.value };
+    }
+    ctx.log(`${key} 上一次的 agent ${last.agentId} 已经停下，但没有有效的结果文件（${validation.error}），新建一个 agent`);
+    return {};
+  }
+  if (status === "timeout" || status === "permission") {
+    if ((last.reattached ?? 0) < 1) return { agent, reattached: (last.reattached ?? 0) + 1 };
+    ctx.log(`${key} 上一次的 agent ${last.agentId} 已经等过两轮仍未完成，停止它并新建一个 agent`);
+    await ctx.runtime
+      .interruptAgent(last.agentId, "这一步已超时，流水线会另起一个 agent 重做。请立即停止当前工作，不要再修改任何文件，也不要写结果文件，直接结束。")
+      .catch((error: Error) => ctx.log(`无法停止 agent ${last.agentId}：${error.message}`));
+    // Give it a moment to wind down before the new agent touches the same files.
+    await agent.wait(Math.min(60_000, ctx.config.waitChunkSeconds * 1000 * 2)).catch(() => undefined);
+    return {};
+  }
+  return {};
+}
+
 /** phases.verify.agents applies to the verify-phase steps. */
 function phaseAgent(ctx: PipelineContext, id: StepId): AgentProfile | undefined {
   if (!VERIFY_PHASE_STEPS.includes(id)) return undefined;

package/engine/src/runtime.ts

@@ -111,6 +111,8 @@ export interface AgentRuntime {
    */
   verifyOrigin(agentId: string, cwd: string): Promise<void>;
   startAgent(input: StartAgentInput): Promise<StepAgent>;
+  /** An agent started earlier (possibly by another pipeline process), to check on, wait for or follow up. */
+  attachAgent(agentId: string): StepAgent;
   /**
    * Starts a requirement's own chat (1.10): a top-level agent working in the repository, given
    * `prompt` and not waited for. It is the chat the requirement's pipeline is later launched

package/engine/src/state.ts

@@ -43,6 +43,13 @@ export interface StepRecord {
   usage?: AgentUsage | null;
   /** Phase the step ran in; absent before 1.7 (develop or verify by step). */
   phase?: PhaseName;
+  /**
+   * 1.11: the step failed while its agent was still at work (timed out, or its status could
+   * not be read). The next run of the step checks that agent before starting another one.
+   */
+  leftRunning?: boolean;
+  /** 1.11: how many times a later run went on waiting for this record's agent instead of starting a new one. */
+  reattached?: number;
 }
 
 export interface PipelineState {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-req-kit",
-  "version": "1.11.0-beta.1",
+  "version": "1.11.0",
   "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",

package/paseo-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "req-kit-paseo-plugin",
-  "version": "1.11.0-beta.1",
+  "version": "1.11.0",
   "private": true,
   "description": "The req-kit plugin for Paseo. Ships inside the paseo-req-kit package; installed with req plugin install.",
   "type": "module",