paseo-req-kit 0.0.0-stage → 1.7.0-beta.3

package/engine/src/main.ts

@@ -0,0 +1,313 @@
+// The long-running pipeline process. Normally started by launch.ts, detached
+// from the chat agent's shell; can also be run in the foreground for debugging.
+
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { LAUNCHER, parseLaunchArgs, resumeCommand, statusCommand, verifyCommand } from "./cli-args.js";
+import { dequeuedMessage, queuedMessage, watchdogPrompt } from "./messages.js";
+import { slotHolders, slotsDir, tryAcquireSlot } from "./queue.js";
+import { cronEvery, parseStartTime } from "./schedule-time.js";
+import { loadConfig, PHASE_MODE_LABELS, PROFILE_LABELS } from "./config.js";
+import { defaultConfigPath, kitVersion, localPromptsDir, PRINCIPLES_INDEX, PROMPTS_DIR } from "./locations.js";
+import { satisfies } from "./daemon-check.js";
+import { describeAgentProfile, resolveConfigProfiles, usesPaseoProfiles } from "./paseo-profiles.js";
+import { runPipeline } from "./pipeline.js";
+import { preflight, verifyPhaseProblem } from "./preflight.js";
+import { loadRuntimeFactory } from "./runtime-loader.js";
+import {
+  acquireLock,
+  ensurePipelineDir,
+  hashFile,
+  type PipelineState,
+  pipelineDir,
+  type RunPhases,
+  STATE_VERSION,
+  statePath,
+  writeState,
+} from "./state.js";
+
+function headCommit(repo: string): string | null {
+  try {
+    return execFileSync("git", ["rev-parse", "HEAD"], { cwd: repo, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+function log(message: string): void {
+  console.log(`[${new Date().toISOString()}] ${message}`);
+}
+
+async function main(): Promise<number> {
+  const args = parseLaunchArgs(process.argv.slice(2));
+  const configPath = args.configPath ?? defaultConfigPath();
+  const checked = preflight(args, hashFile);
+  const { repo, featureDir, mode } = checked;
+  const loaded = loadConfig(configPath, repo);
+  const { sources, ignored } = loaded;
+  let config = loaded.config;
+  log(`req-kit ${kitVersion()}；配置：${sources.join(" → ")}`);
+  if (ignored.length > 0) log(`${ignored.join("、")} 只能在本机配置中设置，已忽略`);
+  if (config.requiredVersion && !satisfies(kitVersion(), config.requiredVersion)) {
+    log(`提醒：团队或项目要求 req-kit ${config.requiredVersion}，当前为 ${kitVersion()}。流水线照常运行，请找时间升级（见 /req-doctor）。`);
+  }
+
+  ensurePipelineDir(repo, featureDir);
+  const release = acquireLock(repo, featureDir);
+  const stateFile = statePath(repo, featureDir);
+  const now = new Date().toISOString();
+  const specHash = hashFile(checked.specPath);
+
+  const createRuntime = await loadRuntimeFactory();
+  const runtime = await createRuntime({ config, log });
+
+  // A resume without --origin-agent keeps reporting to the chat that started the run.
+  const originAgentId = args.originAgentId ?? (mode.kind === "fresh" ? null : mode.previous.originAgentId);
+
+  const previousState = mode.kind === "fresh" ? null : mode.previous;
+  const reuse = mode.kind === "resume-reuse";
+  // Execution mode: --phases, else what this run already uses (continuing), else the spec, else the config.
+  let phaseMode =
+    args.phases ?? (reuse ? previousState?.phases?.mode : null) ?? checked.specPhases ?? previousState?.phases?.mode ?? config.phases.mode;
+  // --verify-at only makes sense with a gate; asking for it implies one.
+  if (args.verifyAt && phaseMode === "continuous" && !args.phases) phaseMode = "gated";
+  const phases: RunPhases = {
+    mode: phaseMode,
+    environment: args.verifyEnv ?? previousState?.phases?.environment ?? config.phases.verify.environment,
+    defects: args.defects ?? previousState?.phases?.defects ?? config.phases.verify.defects,
+  };
+  const verifyAtText = args.verifyAt ?? null;
+  const verifyAt = verifyAtText ? (parseStartTime(verifyAtText) ?? (Number.isNaN(Date.parse(verifyAtText)) ? null : new Date(verifyAtText))) : null;
+
+  // Checked before the state file is touched, so a refused launch leaves no record behind.
+  {
+    try {
+      // In a worktree created for the requirement, the chat stays in the checkout it was cut from.
+      const chatDir = args.sourceRepo ?? (mode.kind === "fresh" ? null : mode.previous.worktree?.sourceRepo) ?? repo;
+      if (verifyAtText && !verifyAt) throw new Error(`看不懂测试验证的开始时间"${verifyAtText}"`);
+      if (verifyAtText && phases.mode === "develop-only") throw new Error("只做研发时没有测试验证阶段，--verify-at 不适用");
+      if (checked.entersVerify) {
+        const problem = verifyPhaseProblem(repo, featureDir, phases.environment);
+        if (problem) throw new Error(problem);
+      }
+      if (originAgentId) await runtime.verifyOrigin(originAgentId, chatDir);
+      if (usesPaseoProfiles(config)) config = resolveConfigProfiles(config, await runtime.listPaseoProfiles());
+    } catch (error) {
+      const reason = (error as Error).message;
+      log(`未启动：${reason}`);
+      if (originAgentId) {
+        await runtime
+          .notifyAgent(originAgentId, `【需求开发流水线通知】这条消息来自后台流水线，不是用户发的。流水线没有启动：${reason}`)
+          .catch(() => undefined);
+      }
+      await runtime.close().catch(() => undefined);
+      release();
+      return 2;
+    }
+  }
+
+  log(`builder：${describeAgentProfile(config.agents.builder)}；reviewer：${describeAgentProfile(config.agents.reviewer)}`);
+
+  const previous = mode.kind === "fresh" ? null : mode.previous;
+  const profile =
+    args.profile ?? (mode.kind === "resume-reuse" ? previous?.profile : null) ?? checked.specProfile ?? config.defaultProfile;
+
+  let state: PipelineState;
+  if (mode.kind === "fresh") {
+    state = {
+      version: STATE_VERSION,
+      repo,
+      featureDir,
+      status: "running",
+      attempt: 1,
+      specHash,
+      originAgentId,
+      pid: process.pid,
+      startedAt: now,
+      updatedAt: now,
+      results: {},
+      history: [],
+      stopReason: null,
+      outcome: null,
+      profile,
+      branch: checked.branch,
+      milestones: [],
+      incremental: null,
+      worktree: args.sourceRepo && args.workspaceId ? { workspaceId: args.workspaceId, sourceRepo: args.sourceRepo } : null,
+      phases,
+      phase: "develop",
+      verifyAt: verifyAt?.toISOString() ?? null,
+      handbacks: 0,
+    };
+    log(`开始新的流水线：${featureDir}（${PROFILE_LABELS[profile]}档，执行方式：${PHASE_MODE_LABELS[phases.mode]}，分支 ${checked.branch ?? "无"}）`);
+  } else {
+    const startOver = mode.kind !== "resume-reuse";
+    const previousImplemented = Object.keys(mode.previous.results).some((k) => k === "implement") ||
+      mode.previous.history.some((h) => h.stepId === "implement" && h.outcome === "completed");
+    state = {
+      ...mode.previous,
+      status: "running",
+      attempt: startOver ? mode.previous.attempt + 1 : mode.previous.attempt,
+      specHash,
+      // A later launch from a different chat moves notifications to that chat.
+      originAgentId,
+      pid: process.pid,
+      results: startOver ? {} : mode.previous.results,
+      stopReason: null,
+      outcome: null,
+      profile,
+      branch: checked.branch,
+      // Older state files have no milestones; a fresh attempt sends them again.
+      milestones: startOver ? [] : (mode.previous.milestones ?? []),
+      incremental:
+        mode.kind === "resume-from-design"
+          ? { fromAttempt: mode.previous.attempt, reason: mode.reason, baseCommit: headCommit(repo), hadImplementation: previousImplemented }
+          : mode.kind === "restart"
+            ? null
+            : (mode.previous.incremental ?? null),
+      phases,
+      // The verify phase starts when development is done; any other start over goes back to development.
+      phase: checked.entersVerify ? "verify" : startOver ? "develop" : (mode.previous.phase ?? "develop"),
+      verifyAt: checked.entersVerify ? null : (verifyAt?.toISOString() ?? (startOver ? null : (mode.previous.verifyAt ?? null))),
+      handbacks: mode.kind === "restart" ? 0 : (mode.previous.handbacks ?? 0),
+    };
+    if (checked.entersVerify) {
+      // A develop-only run that ends with its development report gets a full report after verification.
+      delete state.results.report;
+      log(`开始测试验证阶段（${phases.environment === "deployed" ? "已部署的测试环境" : "本地"}，缺陷处理：${phases.defects}）`);
+    }
+    const why = mode.kind === "resume-from-design" ? mode.reason : mode.kind === "restart" ? "按 --restart 从头开始" : "从中断处继续，已完成的步骤沿用结果";
+    log(`继续流水线：${featureDir}（第 ${state.attempt} 次尝试，${PROFILE_LABELS[profile]}档）—— ${why}`);
+  }
+  writeState(stateFile, state);
+  if (state.worktree) log(`在为这个需求新建的工作区中开发：${repo}（Paseo 工作区 ${state.worktree.workspaceId}，对话所在目录 ${state.worktree.sourceRepo}）`);
+
+  if (state.worktree && mode.kind === "fresh") {
+    // paseo.json's worktree.setup (installing dependencies, copying .env) runs in the background.
+    const setup = await runtime.waitForWorkspaceSetup(state.worktree.workspaceId, 30 * 60_000).catch(() => ({ status: "none" as const, error: null }));
+    if (setup.status === "completed") log("新工作区的环境准备（paseo.json）已完成");
+    else if (setup.status === "failed" || setup.status === "timeout") {
+      const why = setup.status === "timeout" ? "30 分钟内没有完成" : `失败：${setup.error ?? "原因未知"}`;
+      log(`新工作区的环境准备（paseo.json）${why}。流水线继续，步骤会按验证方法自行准备环境。`);
+    }
+  }
+
+  // The chat's own directory: a tester's chat may sit in another checkout of the same repository.
+  const chatRepo = args.sourceRepo ?? state.worktree?.sourceRepo ?? repo;
+  const commands = {
+    resume: resumeCommand({ repo: chatRepo, featureDir, configPath: args.configPath }),
+    status: statusCommand({ repo: chatRepo, featureDir, configPath: args.configPath }),
+    verify: verifyCommand({ repo: chatRepo, featureDir, configPath: args.configPath }),
+  };
+  const notify = async (text: string) => {
+    log(`通知：\n${text}`);
+    if (originAgentId) await runtime.notifyAgent(originAgentId, text).catch((error: Error) => log(`通知发送失败：${error.message}`));
+  };
+
+  // Reminders and automatic continuations from the previous run are no longer needed.
+  if (state.schedules?.length) {
+    for (const s of state.schedules) await runtime.cancelSchedule(s.id).catch((error: Error) => log(`取消定时任务 ${s.id} 失败：${error.message}`));
+    log(`已取消上次运行留下的 Paseo 定时任务：${state.schedules.map((s) => s.kind).join("、")}`);
+    state.schedules = [];
+    writeState(stateFile, state);
+  }
+
+  let releaseSlot = () => {};
+  const shutdown = (signal: string) => {
+    log(`收到 ${signal}，流水线停止`);
+    state.status = "failed";
+    state.stopReason = `流水线进程被 ${signal} 终止`;
+    state.queuedSince = null;
+    writeState(stateFile, state);
+    releaseSlot();
+    release();
+    process.exit(1);
+  };
+  process.once("SIGTERM", () => shutdown("SIGTERM"));
+  process.once("SIGINT", () => shutdown("SIGINT"));
+
+  // Machine-wide limit on concurrent pipelines: wait for a free slot.
+  if (config.maxConcurrentPipelines > 0) {
+    const dir = slotsDir();
+    const holder = { pid: process.pid, repo, featureDir, since: new Date().toISOString() };
+    let slot = tryAcquireSlot(dir, config.maxConcurrentPipelines, holder);
+    if (!slot) {
+      const since = Date.now();
+      state.queuedSince = new Date(since).toISOString();
+      writeState(stateFile, state);
+      log(`本机同时运行的流水线已达上限（${config.maxConcurrentPipelines}），排队等待`);
+      await notify(queuedMessage({ featureDir, max: config.maxConcurrentPipelines, holders: slotHolders(dir) }));
+      while (!slot) {
+        await new Promise((resolve) => setTimeout(resolve, config.queuePollSeconds * 1000));
+        slot = tryAcquireSlot(dir, config.maxConcurrentPipelines, holder);
+      }
+      state.queuedSince = null;
+      writeState(stateFile, state);
+      log("排队结束，开始运行");
+      await notify(dequeuedMessage({ featureDir, waitedMinutes: (Date.now() - since) / 60_000 }));
+    }
+    releaseSlot = slot;
+  }
+
+  // Optional watchdog: the chat checks on the run now and then and continues it if the process died.
+  let watchdog: string | null = null;
+  if (config.watchdogMinutes > 0 && originAgentId) {
+    watchdog = await runtime
+      .scheduleMessage({
+        agentId: originAgentId,
+        cron: cronEvery(config.watchdogMinutes),
+        expiresAt: new Date(Date.now() + 3 * 24 * 3600_000),
+        name: `req-kit 定时检查：${path.basename(featureDir)}`,
+        prompt: watchdogPrompt({ featureDir, statusCommand: commands.status, resumeCommand: commands.resume }),
+      })
+      .catch((error: Error) => {
+        log(`预约定时检查失败：${error.message}`);
+        return null;
+      });
+    if (watchdog) {
+      state.schedules = [...(state.schedules ?? []), { id: watchdog, kind: "watchdog", at: null }];
+      writeState(stateFile, state);
+      log(`已预约定时检查（每 ${config.watchdogMinutes} 分钟，Paseo 定时任务 ${watchdog}）`);
+    }
+  }
+
+  try {
+    const outcome = await runPipeline({
+      repo,
+      featureDir,
+      config,
+      runtime,
+      state,
+      statePath: stateFile,
+      prompts: { promptsDir: PROMPTS_DIR, localPromptsDir: localPromptsDir(), principlesFile: PRINCIPLES_INDEX },
+      logPath: path.join(pipelineDir(repo, featureDir), "pipeline.log"),
+      // Run from the chat, whose directory is the source checkout when the requirement has its own worktree.
+      resumeCommand: commands.resume,
+      statusCommand: commands.status,
+      verifyCommand: commands.verify,
+      log,
+      sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    });
+    log(`流水线结束：${outcome}`);
+    return outcome === "completed" || outcome === "phase_done" ? 0 : outcome === "waiting_for_business" ? 3 : 1;
+  } finally {
+    // The run ended by itself: the watchdog has nothing left to watch.
+    if (watchdog) {
+      await runtime.cancelSchedule(watchdog).catch(() => undefined);
+      state.schedules = (state.schedules ?? []).filter((s) => s.id !== watchdog);
+      writeState(stateFile, state);
+    }
+    await runtime.close().catch(() => undefined);
+    releaseSlot();
+    release();
+  }
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error: Error) => {
+    console.error(`[${new Date().toISOString()}] 流水线无法启动：${error.message}`);
+    console.error(`启动命令：${LAUNCHER}`);
+    process.exit(2);
+  },
+);

package/engine/src/messages.ts

@@ -0,0 +1,308 @@
+// Text the pipeline sends into the chat that launched it, and follow-ups it
+// sends to step agents. Messages to the chat are read by that chat's agent, who
+// relays them to the person who asked for the change (not a developer), so each one says what to tell the user
+// and what to do next.
+
+const HEADER =
+  "【需求开发流水线通知】这条消息来自后台运行的开发流水线，不是用户发的。请把要点转告用户：讲需求和结果，不讲代码实现，除非用户问起。";
+
+export function blockedMessage(input: {
+  featureDir: string;
+  questions: string[];
+  resumeCommand: string;
+  /** A reminder is scheduled after this many hours without an answer. */
+  reminderHours?: number | null;
+}): string {
+  const list = input.questions.map((q, i) => `${i + 1}. ${q}`).join("\n");
+  return [
+    HEADER,
+    "",
+    `功能目录：${input.featureDir}`,
+    "情况：方案审核发现有问题必须由需求方决定，否则可能做出错误的东西。流水线已暂停，还没有开始写代码。",
+    "",
+    "需要用户决定的问题：",
+    list,
+    "",
+    "请这样处理：",
+    "1. 按需求对齐时的方式，逐个向用户提问（给出选项和你的推荐）。",
+    "2. 把答案记入功能目录下的 alignment.md，并更新 spec.md（顶部\"版本\"加 1，在 changes.md 中记录这次变更）。",
+    "3. 把更新后的要点讲给用户听，请用户再次确认 spec（保持顶部为 \"- 状态：已确认\"，并更新日期）。",
+    "4. 用户确认后执行下面的命令，流水线会从方案设计开始，在已有方案的基础上处理这些回答：",
+    "",
+    input.resumeCommand,
+    ...(input.reminderHours ? ["", `（如果 ${input.reminderHours} 小时内还没有回答，会在这个对话里提醒一次。）`] : []),
+  ].join("\n");
+}
+
+export function permissionMessage(input: {
+  stepTitle: string;
+  agentTitle: string;
+  requests: string[];
+}): string {
+  return [
+    HEADER,
+    "",
+    `流水线的「${input.stepTitle}」步骤在等待权限批准，批准前会一直停在这里：`,
+    ...input.requests.map((r) => `- ${r}`),
+    "",
+    `请告诉用户：在 Paseo 中打开名为「${input.agentTitle}」的 agent，查看并批准这个请求（或拒绝）。`,
+    "如果这类等待经常出现，说明流水线配置中的 agent 模式还会询问权限，需要把配置中的 agent 改成免确认模式（运行 /req-doctor 可以查看当前配置）。",
+  ].join("\n");
+}
+
+export function failedMessage(input: {
+  stepTitle: string;
+  reason: string;
+  logPath: string;
+  resumeCommand: string;
+  /** An automatic continuation is scheduled at this time (text). */
+  autoResumeAt?: string | null;
+}): string {
+  return [
+    HEADER,
+    "",
+    `流水线在「${input.stepTitle}」步骤停止了。`,
+    `原因：${input.reason}`,
+    "",
+    "已完成的步骤会保留。请告诉用户开发暂时中断，并说明原因。用户可以先看日志判断原因；涉及环境、配置或代码的问题请开发同事处理。",
+    `日志：${input.logPath}`,
+    ...(input.autoResumeAt
+      ? [
+          `这是临时错误（例如限流或网络中断），已预约在 ${input.autoResumeAt} 自动继续（Paseo 定时任务，到时会在这个对话里执行继续命令）。请告诉用户这一点；用户不想自动继续时，执行暂停命令即可取消。`,
+          "也可以现在就执行下面的命令继续：",
+        ]
+      : ["问题解决后，执行下面的命令可以从中断的步骤继续："]),
+    "",
+    input.resumeCommand,
+  ].join("\n");
+}
+
+const OUTCOME_TEXT: Record<string, string> = {
+  completed: "已完成，可以验收",
+  completed_with_issues: "已完成，但有遗留问题",
+  not_completed: "未完成",
+};
+
+export function completedMessage(input: {
+  featureDir: string;
+  outcome: string;
+  summary: string;
+  reportPath: string;
+  /** Set for a develop-only run: people test by hand from this handoff note. */
+  handoffPath?: string | null;
+}): string {
+  if (input.handoffPath) {
+    return [
+      HEADER,
+      "",
+      `需求的研发已经完成（执行方式：只做研发，流水线没有做测试验证）。研发结论：${OUTCOME_TEXT[input.outcome] ?? input.outcome}`,
+      "",
+      "摘要：",
+      input.summary,
+      "",
+      `研发报告：${input.reportPath}`,
+      `提测说明：${input.handoffPath}`,
+      "",
+      "请把结论和摘要转告用户，说明接下来需要人工测试：按 /req 的验收手册，以提测说明中的“建议重点测试”和验收标准为线索，带用户逐条测试。",
+      "如果之后想让流水线做测试验证，在用户同意后执行继续命令并加上 --phase verify。",
+    ].join("\n");
+  }
+  return [
+    HEADER,
+    "",
+    `需求开发流水线已经结束。结论：${OUTCOME_TEXT[input.outcome] ?? input.outcome}`,
+    "",
+    "摘要：",
+    input.summary,
+    "",
+    `完整报告：${input.reportPath}`,
+    "",
+    "请把结论和摘要转告用户，并读一下报告中「需要你做的事」一节，提醒用户接下来要做什么。用户有疑问时，以报告和功能目录中的文件为准来回答。",
+  ].join("\n");
+}
+
+export function resultFollowUp(input: { resultFile: string; problem: string }): string {
+  return [
+    `流水线没有拿到本步骤的有效结果：${input.problem}。`,
+    `如果本步骤的工作还没有完成，请先完成它；然后按照"本步骤任务"中"结果文件"一节的要求，把结果写入 ${input.resultFile}（只含一个 JSON 对象），再结束。`,
+  ].join("\n");
+}
+
+export function milestoneMessage(text: string): string {
+  return [
+    "【需求开发流水线通知 · 进展】这条消息来自后台流水线，不是用户发的。仅告知进展，用一句话转告用户即可，不需要其他操作。",
+    "",
+    text,
+  ].join("\n");
+}
+
+export function specReviewMessage(input: { featureDir: string; verdict: string; issues: string[]; reviewPath: string }): string {
+  if (input.verdict === "ready") {
+    return [
+      HEADER,
+      "",
+      `功能目录：${input.featureDir}`,
+      `需求说明的独立审阅已完成：没有发现需要澄清的问题（详见 ${input.reviewPath}）。`,
+      "请告诉用户这一点，然后继续请用户确认需求说明。",
+    ].join("\n");
+  }
+  return [
+    HEADER,
+    "",
+    `功能目录：${input.featureDir}`,
+    `需求说明的独立审阅已完成：另一个模型发现 ${input.issues.length} 个建议在确认前澄清的问题，详见 ${input.reviewPath}（其中每个问题都写成了带选项和推荐的选择题）：`,
+    "",
+    ...input.issues.map((q, i) => `${i + 1}. ${q}`),
+    "",
+    "请这样处理：",
+    "1. 先读审阅文件，自己核对一遍：不成立的问题直接略过，并在最后告诉用户略过了哪些、为什么。",
+    "2. 成立的问题，按需求对齐时的方式一次一个地问用户（用审阅文件中的选项和推荐）。",
+    "3. 把答案记入 alignment.md，更新 spec.md，再请用户确认需求说明。",
+  ].join("\n");
+}
+
+export function specReviewFailedMessage(input: { featureDir: string; reason: string }): string {
+  return [
+    HEADER,
+    "",
+    `功能目录：${input.featureDir}`,
+    `需求说明的独立审阅没有完成：${input.reason}`,
+    "这不影响继续：请告诉用户审阅没能完成，然后照常请用户确认需求说明。",
+  ].join("\n");
+}
+
+/** Sent by a Paseo schedule into the chat when a decision has been waited for a long time. */
+export function waitingReminderMessage(input: { featureDir: string; hours: number; questions: string[]; resumeCommand: string }): string {
+  return [
+    "【需求开发流水线通知】这是一条预约的提醒，不是用户发的。",
+    "",
+    `功能目录：${input.featureDir}`,
+    `这个需求在等需求方回答方案审核提出的问题，已经超过 ${input.hours} 小时，开发一直暂停着：`,
+    ...input.questions.map((q, i) => `${i + 1}. ${q}`),
+    "",
+    "请先执行查看进度的命令确认：仍然是\"等待需求方决定\"时，在用户下次说话时提醒他这几个问题，并按之前的方式逐个询问；用户已经回答、开发已经继续或停止时，忽略这条提醒，不要打扰用户。",
+    `回答完、更新需求说明后，继续的命令是：${input.resumeCommand}`,
+  ].join("\n");
+}
+
+/** Sent by a Paseo schedule into the chat to continue after a transient error. */
+export function autoResumePrompt(input: { featureDir: string; reason: string; statusCommand: string; resumeCommand: string }): string {
+  return [
+    "【需求开发流水线通知】这是一条预约的自动继续，不是用户发的。",
+    "",
+    `功能目录：${input.featureDir}`,
+    `开发流水线之前因为临时错误中断：${input.reason}`,
+    "",
+    "请这样处理：",
+    `1. 先执行查看进度的命令：${input.statusCommand}`,
+    "2. 仍然是\"已中断，可以继续\"时，执行下面的继续命令，然后用一句话告诉用户已经自动继续：",
+    `   ${input.resumeCommand}`,
+    "3. 其他情况（已经在运行、已完成、用户已经手动处理过）：什么也不做，也不要回复用户。",
+  ].join("\n");
+}
+
+/** Sent by a Paseo schedule into the chat while a pipeline runs (watchdogMinutes). */
+export function watchdogPrompt(input: { featureDir: string; statusCommand: string; resumeCommand: string }): string {
+  return [
+    "【需求开发流水线通知】这是一条定时检查，不是用户发的。",
+    "",
+    `请执行查看进度的命令：${input.statusCommand}`,
+    `- 输出中的状态是"已中断（后台进程意外退出，可以继续）"：执行继续命令 ${input.resumeCommand}，然后用一句话告诉用户开发在意外中断后已经自动继续。`,
+    "- 其他任何情况：什么也不做，不要回复用户，不要打扰用户。",
+    `（功能目录：${input.featureDir}。这个检查在流水线结束后会自动取消。）`,
+  ].join("\n");
+}
+
+export function queuedMessage(input: { featureDir: string; max: number; holders: Array<{ featureDir: string; repo: string }> }): string {
+  return [
+    HEADER,
+    "",
+    `功能目录：${input.featureDir}`,
+    `这台机器同时最多运行 ${input.max} 条开发流水线，现在已经满了，这个需求在排队，轮到时会自动开始并通知这个对话：`,
+    ...input.holders.map((h) => `- 正在运行：${h.featureDir}（${h.repo}）`),
+    "",
+    "请把这一点告诉用户。不想等的话，可以执行暂停命令取消排队。",
+  ].join("\n");
+}
+
+export function dequeuedMessage(input: { featureDir: string; waitedMinutes: number }): string {
+  return [HEADER, "", `功能目录：${input.featureDir}`, `排队结束（等了约 ${Math.max(1, Math.round(input.waitedMinutes))} 分钟），开发已经开始。请用一句话告诉用户。`].join("\n");
+}
+
+export function scheduledStartPrompt(input: { featureDir: string; command: string }): string {
+  return [
+    "【需求开发流水线通知】这是用户之前预约的开发开始时间，不是用户现在发的消息。",
+    "",
+    `功能目录：${input.featureDir}`,
+    "请执行下面的启动命令，然后用一句话告诉用户预约的开发已经开始（输出\"未启动\"时，按 /req 中的说明处理并告诉用户原因）：",
+    "",
+    input.command,
+  ].join("\n");
+}
+
+const ENVIRONMENT_HINT = {
+  local: "测试验证会在本地启动服务进行。",
+  deployed: "测试验证会在已部署的测试环境中进行：开始前要先把版本部署到测试环境，并在功能目录写好 test-env.md（地址、账号从哪里取、可以用的测试数据；不写口令本身）。",
+} as const;
+
+/** The develop phase is done and the run stopped at the gate (phases.mode "gated"). */
+export function phaseDoneMessage(input: {
+  featureDir: string;
+  handoffPath: string;
+  verifyCommand: string;
+  environment: "local" | "deployed";
+  /** The verify phase is scheduled at this time (text). */
+  verifyAt?: string | null;
+  /** A reminder is scheduled after this many hours. */
+  reminderHours?: number | null;
+  /** How many times verification has handed defects back so far. */
+  handbacks?: number;
+}): string {
+  return [
+    HEADER,
+    "",
+    `功能目录：${input.featureDir}`,
+    `研发阶段已经完成${input.handbacks ? `（这是测试退回后第 ${input.handbacks} 次修复完成）` : ""}：代码已写完并通过代码评审，提测说明在 ${input.handoffPath}。按这个需求的执行方式（分阶段），流水线在这里停下，等待测试验证。`,
+    "",
+    "请这样处理：",
+    "1. 告诉用户研发已完成、可以提测，用两三句话讲提测说明里\"这次改了什么\"和\"建议重点测试\"。",
+    `2. ${ENVIRONMENT_HINT[input.environment]}`,
+    input.verifyAt
+      ? `3. 已预约在 ${input.verifyAt} 自动开始测试验证（Paseo 定时任务）。用户想提前开始或改用别的方式时，按 /req 的"开始测试验证"手册处理；想取消预约，执行暂停命令。`
+      : "3. 用户（或测试同事）准备好之后，按 /req 的\"开始测试验证\"手册处理；确认后执行下面的命令：",
+    "",
+    input.verifyCommand,
+    ...(input.reminderHours && !input.verifyAt ? ["", `（如果 ${input.reminderHours} 小时内还没有开始测试验证，会在这个对话里提醒一次。）`] : []),
+  ].join("\n");
+}
+
+/** Sent by a Paseo schedule when a requirement has waited at the gate for a long time. */
+export function phaseWaitingReminderMessage(input: { featureDir: string; hours: number; handoffPath: string; verifyCommand: string }): string {
+  return [
+    "【需求开发流水线通知】这是一条预约的提醒，不是用户发的。",
+    "",
+    `功能目录：${input.featureDir}`,
+    `这个需求的研发已经完成超过 ${input.hours} 小时，一直在等待测试验证（提测说明：${input.handoffPath}）。`,
+    "",
+    "请先执行查看进度的命令确认：仍然是\"研发完成，待测试验证\"时，在用户下次说话时提醒他可以提测了；已经开始测试验证、已完成或已停止时，忽略这条提醒，不要打扰用户。",
+    `开始测试验证的命令是：${input.verifyCommand}`,
+  ].join("\n");
+}
+
+/** Sent by a Paseo schedule at the time given with --verify-at. */
+export function verifyStartPrompt(input: { featureDir: string; statusCommand: string; verifyCommand: string; environment: "local" | "deployed" }): string {
+  return [
+    "【需求开发流水线通知】这是用户之前预约的测试验证开始时间，不是用户现在发的消息。",
+    "",
+    `功能目录：${input.featureDir}`,
+    "请这样处理：",
+    `1. 先执行查看进度的命令：${input.statusCommand}`,
+    "2. 状态是\"研发完成，待测试验证\"时：" +
+      (input.environment === "deployed"
+        ? "检查功能目录里有 test-env.md；有就执行下面的命令，没有就不要启动，等用户下次说话时告诉他需要先写好测试环境说明。"
+        : "执行下面的命令。") +
+      "然后用一句话告诉用户预约的测试验证已经开始（输出\"未启动\"时告诉用户原因）：",
+    `   ${input.verifyCommand}`,
+    "3. 其他情况（已经开始、已完成、用户已经手动处理过）：什么也不做，也不要回复用户。",
+  ].join("\n");
+}