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

package/engine/src/messages.ts

@@ -0,0 +1,394 @@
+// 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;
+  /** "reproduce": the defect could not be reproduced (defect playbook); default: the design review. */
+  source?: "design_review" | "reproduce";
+}): string {
+  const list = input.questions.map((q, i) => `${i + 1}. ${q}`).join("\n");
+  return [
+    HEADER,
+    "",
+    `功能目录：${input.featureDir}`,
+    input.source === "reproduce"
+      ? "情况：复现与定位这一步没能复现这个缺陷，需要需求方补充信息（复现步骤、环境、账号或数据、截图或报错）。流水线已暂停，还没有修改代码。"
+      : "情况：方案审核发现有问题必须由需求方决定，否则可能做出错误的东西。流水线已暂停，还没有开始写代码。",
+    "",
+    "需要用户决定的问题：",
+    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");
+}
+
+/** Sent to the step agent when checks that passed before its change now fail (the quality gate). */
+export function gateFollowUp(input: {
+  failures: Array<{ name: string; command: string; cwd: string | null; logFile: string; tail: string }>;
+  round: number;
+  max: number;
+  /** Checks that already failed before this requirement's change: not this step's problem. */
+  preexisting: string[];
+}): string {
+  const parts = [
+    `流水线在你这一步结束后运行了项目的检查（质量门），以下检查在改动之前通过、现在失败（第 ${input.round} 次要求修复，最多 ${input.max} 次）：`,
+    "",
+  ];
+  for (const f of input.failures) {
+    parts.push(`### ${f.name}`, "", `命令：\`${f.command}\`${f.cwd ? `（在 ${f.cwd} 目录）` : ""}`, `完整输出：${f.logFile}`, "", "最后的输出：", "", "```text", f.tail, "```", "");
+  }
+  if (input.preexisting.length > 0) parts.push(`（${input.preexisting.join("、")} 在改动之前就失败，不算本次引入，不需要处理。）`, "");
+  parts.push(
+    "请找到原因并修复，让这些检查重新通过；修复要针对原因，不要删除、跳过或放宽检查和测试。修完自己运行一遍这些命令确认通过，提交，并在本步骤的产物里记一笔（哪个检查、原因、怎么修的）；结果文件按需要更新。",
+    "确实修不了的（例如需要环境或权限），在产物里写明原因后照常结束，流水线会把它带进评审和报告。",
+  );
+  return parts.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");
+}
+
+/** The design waits at the confirmation point (designApproval). */
+export function approvalMessage(input: {
+  featureDir: string;
+  previewPath: string;
+  /** The prototype (UI changes), when the design made one. */
+  prototypePath: string | null;
+  approveCommand: string;
+  resumeCommand: string;
+  reminderHours?: number | null;
+  /** The run carries on with the design at this time (text) without an answer. */
+  autoContinueAt?: string | null;
+}): string {
+  return [
+    `${HEADER.replace("【需求开发流水线通知】", "【需求开发流水线通知 · 请确认方案】")}`,
+    "",
+    `功能目录：${input.featureDir}`,
+    "情况：方案已经通过审核，还没有开始写代码。开发前请需求方确认\"做完之后会看到什么\"，这时调整的成本最低。",
+    `- 做完后你会看到什么：${input.previewPath}`,
+    ...(input.prototypePath ? [`- 界面原型：${input.prototypePath}（静态页面，可以在浏览器中打开）`] : []),
+    "",
+    "请这样处理：",
+    "1. 读 preview.md，用几句话把要点讲给用户：会看到的变化、主要的假设（尤其是影响界面、数据、权限的），有原型就告诉用户在哪里看。",
+    "2. 问用户：按这个做，还是有要改的地方？",
+    `3. 用户确认后，执行下面的命令继续开发：\n\n${input.approveCommand}`,
+    "4. 用户要改的：按需求对齐时的方式问清楚，把结论记入 alignment.md，更新 spec.md（顶部\"版本\"加 1，在 changes.md 中记一节，原因写\"方案确认时的修改\"），请用户再次确认需求说明，然后执行下面的命令，流水线会从方案设计开始按修改后的需求调整方案，再请用户确认一次：",
+    "",
+    input.resumeCommand,
+    ...(input.reminderHours ? ["", `（如果 ${input.reminderHours} 小时内还没有确认，会在这个对话里提醒一次。）`] : []),
+    ...(input.autoContinueAt ? ["", `（按团队设置，到 ${input.autoContinueAt} 仍没有确认时，会按这个方案继续开发。）`] : []),
+  ].join("\n");
+}
+
+export function approvalReminderMessage(input: { featureDir: string; hours: number; previewPath: string; approveCommand: string }): string {
+  return [
+    "【需求开发流水线通知】这是一条预约的提醒，不是用户发的。",
+    "",
+    `功能目录：${input.featureDir}`,
+    `这个需求的方案等待需求方确认已经超过 ${input.hours} 小时，开发一直暂停着（要确认的内容：${input.previewPath}）。`,
+    "",
+    "请先执行查看进度的命令确认：仍然是\"等待需求方确认方案\"时，在用户下次说话时提醒他看一下并确认；已经确认、开发已经继续或停止时，忽略这条提醒，不要打扰用户。",
+    `用户确认后继续开发的命令是：${input.approveCommand}`,
+  ].join("\n");
+}
+
+export function approvalContinuePrompt(input: { featureDir: string; hours: number; statusCommand: string; approveCommand: string }): string {
+  return [
+    "【需求开发流水线通知】这是一条预约的自动继续，不是用户发的。",
+    "",
+    `功能目录：${input.featureDir}`,
+    `这个需求的方案等待确认已经 ${input.hours} 小时。按团队的设置，超时没有确认时按方案继续开发。`,
+    "",
+    "请这样处理：",
+    `1. 先执行查看进度的命令：${input.statusCommand}`,
+    "2. 仍然是\"等待需求方确认方案\"时，执行下面的命令，然后用一句话告诉用户：方案一直没有确认，已按方案继续开发，之后仍可以修改需求：",
+    `   ${input.approveCommand}`,
+    "3. 其他情况（已经确认、需求已修改、已经停止）：什么也不做，也不要回复用户。",
+  ].join("\n");
+}

package/engine/src/notifiers.ts

@@ -0,0 +1,76 @@
+// External notifiers: local modules the engine calls at key events, in addition to
+// the message it sends into the originating chat. This is the slot for an internal
+// IM (or any other channel); see notifiers/im-template.mjs and contracts/notifier-event.md.
+//
+// A notifier never affects the pipeline: errors and timeouts are logged and ignored.
+
+import { pathToFileURL } from "node:url";
+
+export const NOTIFIER_EVENT_TYPES = ["milestone", "blocked", "permission", "failed", "completed", "digest", "phase_done", "approval"] as const;
+export type NotifierEventType = (typeof NOTIFIER_EVENT_TYPES)[number];
+
+export interface NotifierConfig {
+  /** Absolute path of the module (resolved when the config is loaded). */
+  module: string;
+  /** Events to send; all of them when omitted. */
+  events?: NotifierEventType[];
+  /** Passed to the module as its second argument, e.g. a webhook address or a group ID. */
+  options?: Record<string, unknown>;
+}
+
+export interface NotifierEvent {
+  /** Format version of this object. */
+  schema: 1;
+  type: NotifierEventType;
+  at: string;
+  kitVersion: string;
+  feature: { dir: string; name: string; title: string };
+  repo: string;
+  branch: string | null;
+  profile: string;
+  /** Chat agent the run reports to, if any. */
+  originAgentId: string | null;
+  /** One or two plain sentences, ready to post as is. */
+  text: string;
+  /** Type-specific fields; see contracts/notifier-event.md. */
+  details: Record<string, unknown>;
+}
+
+export type NotifierFunction = (event: NotifierEvent, options: Record<string, unknown>) => unknown;
+
+const TIMEOUT_MS = 15_000;
+
+async function loadNotifier(file: string): Promise<NotifierFunction> {
+  const module = (await import(pathToFileURL(file).href)) as { default?: unknown; notify?: unknown };
+  const fn = module.default ?? module.notify;
+  if (typeof fn !== "function") throw new Error(`${file} 没有导出 notify 函数（export default 或 export function notify）`);
+  return fn as NotifierFunction;
+}
+
+/** Calls every configured notifier that wants this event. Never throws. */
+export async function dispatchNotifiers(
+  notifiers: NotifierConfig[],
+  event: NotifierEvent,
+  log: (message: string) => void,
+): Promise<void> {
+  const wanted = notifiers.filter((n) => !n.events || n.events.includes(event.type));
+  await Promise.all(
+    wanted.map(async (n) => {
+      let timer: NodeJS.Timeout | undefined;
+      try {
+        const fn = await loadNotifier(n.module);
+        await Promise.race([
+          Promise.resolve(fn(event, n.options ?? {})),
+          new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new Error(`超过 ${TIMEOUT_MS / 1000} 秒没有完成`)), TIMEOUT_MS);
+          }),
+        ]);
+        log(`外部通知已发送（${event.type}）：${n.module}`);
+      } catch (error) {
+        log(`外部通知失败（${event.type}，${n.module}）：${(error as Error).message}。不影响流水线。`);
+      } finally {
+        if (timer) clearTimeout(timer);
+      }
+    }),
+  );
+}

package/engine/src/notify-test.ts

@@ -0,0 +1,101 @@
+// Sends one test event to every configured notifier: `req notify-test [--type blocked] [--repo <dir>]`.
+// Lets whoever implements the IM module check it without running a pipeline.
+
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { loadConfig } from "./config.js";
+import { defaultConfigPath, kitVersion } from "./locations.js";
+import { dispatchNotifiers, NOTIFIER_EVENT_TYPES, type NotifierEvent, type NotifierEventType } from "./notifiers.js";
+
+/** A realistic event of the given type, with the details the pipeline would send. */
+export function sampleEvent(type: NotifierEventType, repo: string): NotifierEvent {
+  const featureDir = "docs/features/20261012-sms-login";
+  const resume = `node "<req-kit>/bin/start-pipeline.mjs" --feature ${featureDir} --resume`;
+  const samples: Record<NotifierEventType, { text: string; details: Record<string, unknown> }> = {
+    milestone: { text: "技术方案已经确定（审核 1 轮），开始写代码。", details: { milestone: "design-settled" } },
+    blocked: {
+      text: "方案审核发现 1 个需要需求方决定的问题，流水线已暂停，请到发起的对话中回答。",
+      details: { questions: ["验证码有效期是 5 分钟还是 10 分钟？"], resumeCommand: resume },
+    },
+    permission: {
+      text: "「实现」步骤在等待权限批准，批准前会一直停在这里。",
+      details: { stepTitle: "实现", agentTitle: "实现 · 短信验证码登录", requests: ["运行 npm install"] },
+    },
+    failed: {
+      text: "开发流水线在「代码评审」步骤中断：agent 连续出错。",
+      details: { stepTitle: "代码评审", reason: "agent 连续出错", logPath: `${featureDir}/.pipeline/pipeline.log`, resumeCommand: resume },
+    },
+    digest: {
+      text: "【req-kit 需求总览】shop\n共 3 个需求：需要处理 1，待验收 1，开发中 1。",
+      details: { features: [{ name: "20261012-sms-login", title: "短信验证码登录", stage: "待验收" }] },
+    },
+    phase_done: {
+      text: `研发已完成，可以提测：提测说明在 ${featureDir}/handoff.md。`,
+      details: { handoffPath: `${featureDir}/handoff.md`, mode: "gated", verifyCommand: `${resume} --phase verify`, verifyAt: null, handbacks: 0 },
+    },
+    approval: {
+      text: `方案已通过审核，请需求方确认"做完后会看到什么"再开始写代码：${featureDir}/preview.md`,
+      details: { previewPath: `${featureDir}/preview.md`, approveCommand: resume.replace(/--resume$/, "--approve"), resumeCommand: resume },
+    },
+    completed: {
+      text: "开发流水线已结束：已完成，可以验收。",
+      details: { outcome: "completed", summary: "6 条验收标准全部通过。", reportPath: `${featureDir}/report.md` },
+    },
+  };
+  return {
+    schema: 1,
+    type,
+    at: new Date().toISOString(),
+    kitVersion: kitVersion(),
+    feature: { dir: featureDir, name: "20261012-sms-login", title: "短信验证码登录（测试消息）" },
+    repo,
+    branch: "feature/20261012-sms-login",
+    profile: "standard",
+    originAgentId: null,
+    text: `【测试】${samples[type].text}`,
+    details: samples[type].details,
+  };
+}
+
+async function main(): Promise<number> {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: { type: { type: "string", default: "completed" }, repo: { type: "string" }, config: { type: "string" } },
+  });
+  const type = values.type as NotifierEventType;
+  if (!NOTIFIER_EVENT_TYPES.includes(type)) {
+    console.error(`--type 只能是 ${NOTIFIER_EVENT_TYPES.join("、")} 之一`);
+    return 2;
+  }
+  const repo = path.resolve(values.repo ?? process.cwd());
+  const configPath = values.config ? path.resolve(values.config) : defaultConfigPath();
+  const { config } = loadConfig(configPath, fs.existsSync(repo) ? repo : undefined);
+  if (config.notifiers.length === 0) {
+    console.log(`没有配置外部通知（${configPath} 中的 notifiers 为空）。写法见 notifiers/im-template.mjs 开头的说明。`);
+    return 1;
+  }
+  const wanted = config.notifiers.filter((n) => !n.events || n.events.includes(type));
+  if (wanted.length === 0) {
+    console.log(`配置的通知都没有订阅 ${type} 事件。可以用 --type 换一种，例如 --type ${config.notifiers[0].events?.[0] ?? "completed"}。`);
+    return 1;
+  }
+  let failed = false;
+  // Lets a module show what it would send (the template does) without a real IM.
+  process.env.REQ_KIT_NOTIFY_TEST = "1";
+  await dispatchNotifiers(config.notifiers, sampleEvent(type, repo), (message) => {
+    if (message.startsWith("外部通知失败")) failed = true;
+    console.log(message);
+  });
+  return failed ? 1 : 0;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)) {
+  main().then(
+    (code) => process.exit(code),
+    (error: Error) => {
+      console.error(error.message);
+      process.exit(1);
+    },
+  );
+}

package/engine/src/paseo-json.ts

@@ -0,0 +1,73 @@
+// paseo.json checks shared by the doctor.
+//
+// Paseo 0.11 runs project commands with a different shell on each system:
+//   worktree.setup: bash (macOS, Linux) / powershell -ExecutionPolicy Bypass (Windows)
+//   scripts:        the terminal's shell, $SHELL or /bin/sh (macOS, Linux) / cmd.exe (Windows)
+// paseo.json is committed and shared, so commands should work in all of them: plain program
+// invocations, with environment variables read by the program (see /req-setup's helpers).
+
+export type PaseoJson = { worktree?: { setup?: unknown }; scripts?: Record<string, { type?: string; command?: string; port?: number }> };
+
+export type ShellStyle = "posix" | "powershell" | "cmd";
+
+const STYLE_NAMES: Record<ShellStyle, string> = { posix: "bash/sh", powershell: "PowerShell", cmd: "cmd.exe" };
+
+/** Shell-specific syntax found in a command (empty: works the same everywhere). */
+export function shellStyles(command: string): ShellStyle[] {
+  const styles = new Set<ShellStyle>();
+  if (/\$env:[A-Za-z_]/i.test(command) || /\b(Test-Path|Copy-Item|Set-Location|Get-ChildItem|Remove-Item)\b/.test(command)) styles.add("powershell");
+  if (/%[A-Za-z_][A-Za-z0-9_]*%/.test(command)) styles.add("cmd");
+  if (/(^|[^:\w`])\$\{?(?!env:)[A-Za-z_]/i.test(command) || /\[\s+-[a-z]\s/.test(command) || /(^|\s)(cp|mv|rm|export)\s/.test(command) || /\|\||&&/.test(command)) {
+    // `&&` works in cmd and PowerShell 7 too, but not in Windows PowerShell 5.1, which Paseo uses for setup.
+    styles.add("posix");
+  }
+  return [...styles];
+}
+
+function setupCommands(raw: PaseoJson): string[] {
+  const setup = raw.worktree?.setup;
+  if (Array.isArray(setup)) return setup.map(String);
+  return typeof setup === "string" ? setup.split(/\r?\n/).filter((l) => l.trim()) : [];
+}
+
+export interface PaseoJsonIssue {
+  /** "fails": the command will not work on this machine; "portable": it only works on some systems. */
+  kind: "fails" | "portable";
+  text: string;
+  fix: string;
+}
+
+const FIX =
+  "改成各系统都一样的写法：准备命令用 node scripts/paseo/copy-local-files.mjs .env，服务用 node scripts/paseo/with-port.mjs npm run dev -- --port {PORT}（/req-setup 会写入这两个脚本）";
+
+/** Problems of the project's paseo.json for the system Paseo runs on (process.platform by default). */
+export function paseoJsonIssues(raw: PaseoJson, platform: NodeJS.Platform = process.platform): PaseoJsonIssue[] {
+  const windows = platform === "win32";
+  const setupShell: ShellStyle = windows ? "powershell" : "posix";
+  const scriptShell: ShellStyle = windows ? "cmd" : "posix";
+  const issues: PaseoJsonIssue[] = [];
+  const check = (where: string, command: string, shell: ShellStyle) => {
+    const styles = shellStyles(command);
+    if (styles.length === 0) return;
+    const short = command.length > 60 ? `${command.slice(0, 60)}…` : command;
+    const foreign = styles.filter((s) => s !== shell);
+    if (foreign.length > 0) {
+      issues.push({
+        kind: "fails",
+        text: `${where}「${short}」是 ${foreign.map((s) => STYLE_NAMES[s]).join("、")} 写法，这台机器上 Paseo 用 ${STYLE_NAMES[shell]} 执行，会失败`,
+        fix: FIX,
+      });
+    } else {
+      issues.push({
+        kind: "portable",
+        text: `${where}「${short}」用了 ${STYLE_NAMES[shell]} 的写法，在这台机器上可以用，换到其他系统（Windows 和 macOS/Linux 之间）会失败`,
+        fix: FIX,
+      });
+    }
+  };
+  for (const cmd of setupCommands(raw)) check("paseo.json 的 worktree.setup 中", cmd, setupShell);
+  for (const [name, s] of Object.entries(raw.scripts ?? {})) {
+    check(`paseo.json 的${s.type === "service" ? "服务" : "脚本"} ${name}`, String(s.command ?? ""), scriptShell);
+  }
+  return issues;
+}