paseo-req-kit 1.10.0-beta.3 → 1.11.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 [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
+
+接单器：一台共享研发机器自动接卡片、转达回复，需求方只在卡片上操作。
+
+### 使用者会看到的变化
+
+- **`req factory`**：每隔几分钟（`factory.pollMinutes`，默认 5）检查一次需求管理系统：本机登记的仓库所在空间中，标题以 `[AI]` 或 `【AI】` 开头、还没开始过的卡片，自动按子系统进入对应仓库、开始需求；需求方在卡片中的新回复自动转给需求会话。
+  - `req factory once` 检查一次；`start` / `stop` 在后台运行；`status` 看最近一次检查和没能接的卡片；`service` 给出作为系统服务（开机自动运行）的写法。
+  - 每次最多开始 3 个需求（`factory.maxNewPerPoll`），其余下次再接；接不了的卡片记下原因，卡片改了马上再试，否则一天后再试。
+- **修正**：`req start --from` 在建需求会话时失败（例如 Paseo 没在运行）后，再运行一次会补建会话，而不是提示"已经开始过"。
+
+### 升级须知
+
+- 需要在对接配置中加上 `list`（列出卡片的命令），写法见《项目定制与运行规则》的"接单器"一节；接单的仓库要在 `cardSource` 中写上空间（`projectId`）。
+- 新增配置 `factory`（只能写在本机或团队配置中）、本机目录 `~/.req-kit/factory/`。现在只支持一台机器接单。设计决定见 ADR 0030。
+
 ## 1.10.0-beta.3
 
 从卡片开始的需求：按子系统自动选仓库、研发完成后推送分支、统计按需求方汇总。

package/bin/req.mjs

@@ -36,6 +36,7 @@ const HELP = `req-kit ${version}（${kitRoot}）
   req card publish <卡号>      把需求会话写的 card-ai.md 写进卡片的 AI 区
   req card list                本机从卡片开始的需求
   req card route               本机接收卡片的仓库和子系统（--add <仓库> 登记）
+  req factory start|stop|status  接单器：定时为标题带 [AI] 的新卡片开始需求、转达回复（once 检查一次）
 
 使用情况（可以在任何目录运行）：
   req stats [--since 30d] [--month 2026-10]
@@ -160,6 +161,9 @@ switch (command) {
   case "card":
     code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "card-cmd.ts"), ...rest]) : 1;
     break;
+  case "factory":
+    code = needTsx() ? node([tsxCli, path.join(kitRoot, "engine", "src", "factory.ts"), ...rest]) : 1;
+    break;
   case "doctor":
     code = node([path.join(kitRoot, "bin", "req-doctor.mjs"), ...rest]);
     break;

package/docs/adr/0030-card-intake-process.md

@@ -0,0 +1,22 @@
+# 0030 接单器：共享机器上定时接卡片、转达回复
+
+- 状态：已采纳（1.11.0-beta.1；建在 [0029](0029-requirements-from-cards.md) 之上）
+
+## 背景
+
+1.10 已经可以从一张卡片开始需求（`req start --from`）、把需求方在卡片中的回复转给需求会话（`req card check`），但这两步都要有人运行。"软件工厂"要求需求方只在卡片上操作：写好卡片、标题加上约定的标识，就有一台共享研发机器接手。
+
+## 决定
+
+- **一个常驻进程，两件事**：`req factory run` 每隔 `factory.pollMinutes`（默认 5 分钟）检查一次：先用对接配置的 `list` 命令列出各空间（本机登记仓库的 `cardSource.projectId`）中的卡片，标题以 `factory.titleTags`（默认 `[AI]`、`【AI】`）开头、本机还没开始过的，按 1.10 的 `req start --from` 开始（按子系统选仓库、建需求会话）；再按 `req card check --all` 转达回复，跳过流水线已完成的需求。同一台机器上一次只做一次检查（`~/.req-kit/factory/poll.lock`）。
+- **轮询外部系统，不用回调**：需求管理系统没有我们能用的事件推送；轮询的间隔是几分钟，对需求开发足够，失败了下次再来。卡片状态、条件（例如只查"新建"的用户故事）写在 `list` 的参数里，由团队配置决定。
+- **克制地接单**：每次最多开始 `factory.maxNewPerPoll`（默认 3）个需求，其余下次再接；流水线本身仍受 `maxConcurrentPipelines` 限制。接不了的卡片（例如子系统没有对应的仓库）记下原因，卡片的标题和子系统不变就一天内不再试，`req factory status` 中可以看到。
+- **只读卡片、不改卡片状态来"占位"**：本机的登记（`~/.req-kit/cards/`）就是去重的依据。卡片状态仍只由流水线事件改（开发中、待测试）。将来多台机器同时接单时再引入占位（例如改状态或经内网 Hub 派工），见 [0029](0029-requirements-from-cards.md)。
+- **运行方式交给系统**：`req factory start` / `stop` 在后台运行，适合先试；长期运行用系统服务（`req factory service` 给出 systemd 用户服务或 Windows 计划任务的写法），机器重启后自动恢复。接单器通过 Paseo daemon 创建需求会话，daemon 需要同时运行。
+- **配置只在本机或团队配置中**：`factory` 和 `integrations` 一样会让机器做事，写在项目配置中会被忽略。
+
+## 影响
+
+- 对接配置新增 `list`（参数可用 `{projectId}`、`{page}`、`{pageSize}`、`{titleTag}`；`fields` 写每张卡片中 id、title 等的位置；`items` 写输出中列表的位置，不写时依次找 data.list、data.records、data.items、data.rows、data）。
+- 新增配置 `factory`（`pollMinutes`、`titleTags`、`maxNewPerPoll`）、命令 `req factory once | run | start | stop | status | service`、本机目录 `~/.req-kit/factory/`（日志、状态、没能接的卡片）。
+- `req start --from` 中途失败（例如 Paseo 没在运行，会话没建成）时，再次运行会补建会话，而不是当作已经开始过。

package/docs/adr/README.md

@@ -31,3 +31,4 @@ req-kit 自身的设计决定。修改其中任何一条，请新增一条 ADR
 - [0027 Paseo 插件：随 req-kit 一起发布，只通过 req api 工作](0027-paseo-plugin.md)
 - [0028 外部系统对接：命令写法在配置里，内容由 AI 整理，调用是确定的](0028-external-integrations.md)
 - [0029 从卡片开始的需求：需求会话代替人，卡片描述代替对话](0029-requirements-from-cards.md)
+- [0030 接单器：共享机器上定时接卡片、转达回复](0030-card-intake-process.md)

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

@@ -374,6 +374,43 @@ Paseo 自带的 `/paseo-advisor`、`/paseo-committee` 等编排 skill 也可以
 
 **使用统计**：从卡片开始的需求，运行记录带上需求方（卡片的提出人）和卡号。`req stats --report` 多一节"从卡片开始的需求（按需求方）"，CSV 多 `requester`、`card` 两列。
 
+### 接单器（1.11 起，beta）
+
+接单器在一台共享研发机器上常驻运行，需求方只在卡片上操作：标题以 `[AI]`（或 `【AI】`）开头的新卡片会被自动接手，需求方在卡片中的回复会自动转给需求会话。
+
+在对接配置中再写 `list`（列出卡片的命令），例如：
+
+```json
+"list": {
+  "args": ["alm-card", "list", "--project-id", "{projectId}", "-t", "用户故事", "-S", "新建", "-s", "AI", "-L", "{pageSize}", "-P", "{page}", "--fields", "globalId,name,state,subsysName,createdBy"],
+  "fields": { "id": "globalId", "title": "name", "state": "state", "subsystem": "subsysName", "author": "createdBy" }
+}
+```
+
+- `{projectId}` 是本机登记的仓库在 `cardSource` 中写的空间，每个空间查一次；`{page}`、`{pageSize}` 用于翻页（`pageSize` 默认 100，最多 `maxPages` 页，默认 5）。
+- 输出中卡片列表的位置不在 data.list、data.records、data.items、data.rows 或 data 时，用 `items` 写明，例如 `"items": "data.result"`。
+- 只接什么样的卡片（类型、状态）写在参数里；接单器再按标题开头的标识筛一遍，`-s` 只是让列表短一些。
+
+本机或团队配置中可以调整（都有默认值）：
+
+```json
+"factory": { "pollMinutes": 5, "titleTags": ["[AI]", "【AI】"], "maxNewPerPoll": 3 }
+```
+
+运行：
+
+| 命令 | 做什么 |
+| --- | --- |
+| `req factory once` | 检查一次：为新卡片开始需求，转达新回复。先用它试配置 |
+| `req factory start` / `stop` | 在后台运行 / 停止，日志在 `~/.req-kit/factory/factory.log` |
+| `req factory status` | 是否在运行、最近一次检查的结果、没能接的卡片和原因 |
+| `req factory service` | 作为系统服务运行的写法（Linux systemd 用户服务、Windows 计划任务），机器重启后自动恢复 |
+
+- 每次最多开始 `maxNewPerPoll` 个需求，其余下次再接；开发仍受 `maxConcurrentPipelines` 限制。
+- 接不了的卡片（例如子系统没有对应的仓库）记下原因；卡片的标题和子系统改了会马上再试，否则一天后再试。
+- Paseo daemon 要同时运行：接单器通过它创建需求会话。
+- 现在只支持一台机器接单。几台机器同时运行接单器会重复接同一张卡片。
+
 ## 团队配置
 
 几台机器、多个项目共用的设置（统一的模型、评审小组、超时、要求的 req-kit 版本）可以放在一份团队配置里。把它放进一个团队共用的 git 仓库，各台机器克隆下来，在本机配置 `~/.req-kit/config.json` 中写上它的路径（绝对路径，或相对 `~/.req-kit/` 的路径）：
@@ -434,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/card-cmd.ts

@@ -62,7 +62,7 @@ function fail(message: string): never {
   throw new CardError(message);
 }
 
-function cardIntegrations(config: PipelineConfig): IntegrationConfig[] {
+export function cardIntegrations(config: PipelineConfig): IntegrationConfig[] {
   return config.integrations.filter((i) => i.query);
 }
 
@@ -141,66 +141,100 @@ export interface CardCmdOptions {
   out?: (line: string) => void;
 }
 
-async function startFromCard(argv: string[], opts: CardCmdOptions): Promise<number> {
-  const out = opts.out ?? console.log;
-  const { values } = parseArgs({ args: argv, options: { from: { type: "string" }, repo: { type: "string" }, config: { type: "string" } }, allowPositionals: false });
-  if (!values.from) fail(`缺少 --from\n\n${USAGE}`);
-  const configPath = values.config ? path.resolve(values.config) : defaultConfigPath(opts.env);
-  // Integrations live in the machine or team config, so the card can be read before the repository is known.
-  const { config: integration, id } = parseCardRef(values.from, cardIntegrations(loadConfig(configPath).config));
+export interface BeginResult {
+  status: "started" | "exists";
+  repo: string;
+  featureDir: string;
+  title: string;
+  sessionAgentId: string | null;
+  /** Set when the repository was chosen by the card's subsystem. */
+  routed: boolean;
+}
 
+/**
+ * Starts a requirement from a card: reads it, picks the repository (repoArg, else by subsystem,
+ * else cwd), creates the feature directory and the requirement's chat. A card that already
+ * started is left alone, unless its chat was never created (then that is tried again).
+ */
+export async function beginFromCard(input: { integration: IntegrationConfig; id: string; repoArg: string | null; configPath: string; opts: CardCmdOptions }): Promise<BeginResult> {
+  const { integration, id, opts } = input;
   const existing = findCardEntry(integration.name, id, opts.env);
+  let repo: string;
+  let featureDir: string;
+  let card: Awaited<ReturnType<typeof queryCard>> | null = null;
+  let source: SourceFile;
+  let routed = false;
   if (existing) {
     const where = locateCardRequirement(existing, opts.env) ?? existing.sourceRepo;
-    out(`卡片 ${id} 已经开始过：${path.join(where, existing.featureDir)}。用 req card check ${integration.name}:${id} 转达需求方的新回复。`);
-    return 0;
+    const known = readSource(where, existing.featureDir);
+    if (!known || known.sessionAgentId) {
+      return { status: "exists", repo: where, featureDir: existing.featureDir, title: known?.title ?? "", sessionAgentId: known?.sessionAgentId ?? null, routed: false };
+    }
+    repo = where;
+    featureDir = existing.featureDir;
+    source = known;
+  } else {
+    card = await queryCard(integration, id, opts.run);
+    const cwd = opts.cwd ?? process.cwd();
+    const byRoute = input.repoArg ? null : routeCard(card, integration.name, opts.env);
+    routed = byRoute !== null;
+    repo = gitTop(input.repoArg ? path.resolve(cwd, input.repoArg) : (byRoute ?? cwd));
+    const parts = splitDescription(card.body);
+    featureDir = `docs/features/${today()}-${cardSlug(id)}`;
+    fs.mkdirSync(path.join(repo, featureDir), { recursive: true });
+    fs.writeFileSync(path.join(repo, featureDir, CARD_SOURCE_FILE), cardSourceText(card, parts.original));
+    source = {
+      v: 1,
+      system: integration.name,
+      id,
+      url: card.url,
+      title: card.title,
+      author: card.author,
+      subsystem: card.subsystem,
+      state: card.state,
+      fetchedAt: new Date().toISOString(),
+      sourceRepo: repo,
+      sessionAgentId: null,
+      originalHash: null,
+      replyHash: null,
+      confirmedAt: null,
+      planConfirmedAt: null,
+      progress: null,
+      publishedAt: null,
+    };
+    writeSource(repo, featureDir, source);
+    saveCardEntry({ system: integration.name, id, sourceRepo: repo, featureDir, createdAt: source.fetchedAt }, opts.env);
   }
-
-  const card = await queryCard(integration, id, opts.run);
-  const cwd = opts.cwd ?? process.cwd();
-  const routed = values.repo ? null : routeCard(card, integration.name, opts.env);
-  const repo = gitTop(values.repo ? path.resolve(cwd, values.repo) : (routed ?? cwd));
-  if (routed) out(`按子系统「${card.subsystem}」选择仓库：${repo}`);
-  const config = loadConfig(configPath, repo).config;
-  const parts = splitDescription(card.body);
-  const featureDir = `docs/features/${today()}-${cardSlug(id)}`;
-  fs.mkdirSync(path.join(repo, featureDir), { recursive: true });
-  fs.writeFileSync(path.join(repo, featureDir, CARD_SOURCE_FILE), cardSourceText(card, parts.original));
-  const source: SourceFile = {
-    v: 1,
-    system: integration.name,
-    id,
-    url: card.url,
-    title: card.title,
-    author: card.author,
-    subsystem: card.subsystem,
-    state: card.state,
-    fetchedAt: new Date().toISOString(),
-    sourceRepo: repo,
-    sessionAgentId: null,
-    originalHash: null,
-    replyHash: null,
-    confirmedAt: null,
-    planConfirmedAt: null,
-    progress: null,
-    publishedAt: null,
-  };
-  writeSource(repo, featureDir, source);
-  saveCardEntry({ system: integration.name, id, sourceRepo: repo, featureDir, createdAt: source.fetchedAt }, opts.env);
-
+  const config = loadConfig(input.configPath, repo).config;
   source.sessionAgentId = await withRuntime(config, (runtime, resolved) =>
     runtime.startSessionAgent({
-      title: `需求 ${id}：${card.title}`.slice(0, 120),
-      prompt: sessionStartPrompt({ system: integration.name, id, title: card.title, featureDir }),
+      title: `需求 ${id}：${source.title}`.slice(0, 120),
+      prompt: sessionStartPrompt({ system: integration.name, id, title: source.title, featureDir }),
       cwd: repo,
       profile: resolved.agents.builder,
       labels: { "req-kit": "requirement-session" },
     }),
   );
   writeSource(repo, featureDir, source);
-  out(`已从卡片 ${id}「${card.title}」开始需求。`);
-  out(`功能目录：${path.join(repo, featureDir)}`);
-  out(`需求会话：agent ${source.sessionAgentId}（在 Paseo 中打开它可以看到整理需求的过程）。`);
+  return { status: "started", repo, featureDir, title: source.title, sessionAgentId: source.sessionAgentId, routed };
+}
+
+async function startFromCard(argv: string[], opts: CardCmdOptions): Promise<number> {
+  const out = opts.out ?? console.log;
+  const { values } = parseArgs({ args: argv, options: { from: { type: "string" }, repo: { type: "string" }, config: { type: "string" } }, allowPositionals: false });
+  if (!values.from) fail(`缺少 --from\n\n${USAGE}`);
+  const configPath = values.config ? path.resolve(values.config) : defaultConfigPath(opts.env);
+  // Integrations live in the machine or team config, so the card can be read before the repository is known.
+  const { config: integration, id } = parseCardRef(values.from, cardIntegrations(loadConfig(configPath).config));
+  const result = await beginFromCard({ integration, id, repoArg: values.repo ?? null, configPath, opts });
+  if (result.status === "exists") {
+    out(`卡片 ${id} 已经开始过：${path.join(result.repo, result.featureDir)}。用 req card check ${integration.name}:${id} 转达需求方的新回复。`);
+    return 0;
+  }
+  if (result.routed) out(`按子系统选择仓库：${result.repo}`);
+  out(`已从卡片 ${id}「${result.title}」开始需求。`);
+  out(`功能目录：${path.join(result.repo, result.featureDir)}`);
+  out(`需求会话：agent ${result.sessionAgentId}（在 Paseo 中打开它可以看到整理需求的过程）。`);
   out(`需求说明和问题会写进卡片描述末尾的 AI 区；需求方回复后运行 req card check ${integration.name}:${id}（接单器会定时运行它）。`);
   return 0;
 }
@@ -309,16 +343,14 @@ export async function checkOne(target: Located, opts: CardCmdOptions, notify: (a
   return `${source.id}：已转给需求会话（${changes.join("；")}）`;
 }
 
-async function check(argv: string[], opts: CardCmdOptions): Promise<number> {
-  const out = opts.out ?? console.log;
-  const { values, positionals } = parseArgs({ args: argv, options: { all: { type: "boolean" }, config: { type: "string" } }, allowPositionals: true });
-  if (!positionals[0] && !values.all) fail(`写卡号，或用 --all 检查本机所有从卡片开始的需求\n\n${USAGE}`);
-  const configPath = values.config ? path.resolve(values.config) : defaultConfigPath(opts.env);
-  const targets = locateCards(positionals[0] ?? null, opts, configPath);
-  if (targets.length === 0) {
-    out("本机没有从卡片开始的需求。");
-    return 0;
-  }
+/**
+ * Checks cards for new replies and passes them on. `skipFinished` leaves out requirements whose
+ * pipeline has completed (the intake process uses it to spare the external system).
+ */
+export async function checkCards(ref: string | null, opts: CardCmdOptions, configPath: string, options: { skipFinished?: boolean } = {}): Promise<{ lines: string[]; failed: number; checked: number }> {
+  let targets = locateCards(ref, opts, configPath);
+  if (options.skipFinished) targets = targets.filter((t) => readState(statePath(t.repo, t.entry.featureDir))?.status !== "completed");
+  const lines: string[] = [];
   let runtime: AgentRuntime | null = null;
   const notify = async (agentId: string, text: string) => {
     runtime ??= await (await loadRuntimeFactory())({ config: targets[0].pipelineConfig, log: () => undefined });
@@ -328,16 +360,30 @@ async function check(argv: string[], opts: CardCmdOptions): Promise<number> {
   try {
     for (const target of targets) {
       try {
-        out(await checkOne(target, opts, notify));
+        lines.push(await checkOne(target, opts, notify));
       } catch (error) {
         failed += 1;
-        out(`${target.source.id}：${(error as Error).message}`);
+        lines.push(`${target.source.id}：${(error as Error).message}`);
       }
     }
   } finally {
     await (runtime as AgentRuntime | null)?.close().catch(() => undefined);
   }
-  return failed > 0 ? 1 : 0;
+  return { lines, failed, checked: targets.length };
+}
+
+async function check(argv: string[], opts: CardCmdOptions): Promise<number> {
+  const out = opts.out ?? console.log;
+  const { values, positionals } = parseArgs({ args: argv, options: { all: { type: "boolean" }, config: { type: "string" } }, allowPositionals: true });
+  if (!positionals[0] && !values.all) fail(`写卡号，或用 --all 检查本机所有从卡片开始的需求\n\n${USAGE}`);
+  const configPath = values.config ? path.resolve(values.config) : defaultConfigPath(opts.env);
+  const result = await checkCards(positionals[0] ?? null, opts, configPath);
+  if (result.checked === 0) {
+    out("本机没有从卡片开始的需求。");
+    return 0;
+  }
+  for (const line of result.lines) out(line);
+  return result.failed > 0 ? 1 : 0;
 }
 
 function route(argv: string[], opts: CardCmdOptions): number {

package/engine/src/config.ts

@@ -192,6 +192,12 @@ export interface PipelineConfig {
    * that share a subsystem (e.g. "message-service", "后端").
    */
   cardSource: { system: string; projectId: string | null; subsystems: string[]; titleKeywords: string[] } | null;
+  /**
+   * The intake process (1.11, `req factory`): how often it looks for new cards, which title tags
+   * mark a card for it, and how many requirements it starts per look at most. Machine or team
+   * config only.
+   */
+  factory: { pollMinutes: number; titleTags: string[]; maxNewPerPoll: number };
   /** Automatic retries of a step after a transient error (rate limit, dropped connection). */
   retry: { attempts: number; backoffSeconds: number[] };
   /**
@@ -298,6 +304,7 @@ export const DEFAULT_CONFIG: PipelineConfig = {
   integrationDefaults: {},
   push: { enabled: false, remote: "origin", branchPrefix: "req/" },
   cardSource: null,
+  factory: { pollMinutes: 5, titleTags: ["[AI]", "【AI】"], maxNewPerPoll: 3 },
   retry: { attempts: 2, backoffSeconds: [60, 300] },
   paseoServices: "auto",
   serviceReadySeconds: 120,
@@ -362,6 +369,7 @@ function merge(base: PipelineConfig, raw: Record<string, unknown>): PipelineConf
     merged.integrationDefaults = combined;
   }
   merged.push = { ...base.push, ...(isRecord(raw.push) ? raw.push : {}) } as PipelineConfig["push"];
+  merged.factory = { ...base.factory, ...(isRecord(raw.factory) ? raw.factory : {}) } as PipelineConfig["factory"];
   if (isRecord(raw.cardSource)) {
     const c = raw.cardSource;
     merged.cardSource = {
@@ -563,6 +571,10 @@ function validate(config: PipelineConfig): void {
   if (typeof push.enabled !== "boolean") throw new ConfigError("push.enabled 必须是 true 或 false");
   if (typeof push.remote !== "string" || !/^[\w.-]+$/.test(push.remote)) throw new ConfigError('push.remote 必须是远程仓库名，例如 "origin"');
   if (typeof push.branchPrefix !== "string" || !/^[A-Za-z0-9._-]+\/$/.test(push.branchPrefix)) throw new ConfigError('push.branchPrefix 必须是以 / 结尾的分支前缀，例如 "req/"');
+  const f = config.factory;
+  if (typeof f.pollMinutes !== "number" || !(f.pollMinutes >= 1)) throw new ConfigError("factory.pollMinutes 必须是至少 1 的分钟数");
+  if (!Number.isInteger(f.maxNewPerPoll) || f.maxNewPerPoll < 1) throw new ConfigError("factory.maxNewPerPoll 必须是正整数");
+  if (!Array.isArray(f.titleTags) || f.titleTags.length === 0 || !f.titleTags.every((t) => typeof t === "string" && t.trim())) throw new ConfigError('factory.titleTags 必须是非空的字符串数组，例如 ["[AI]"]');
   const cs = config.cardSource;
   if (cs !== null) {
     if (typeof cs.system !== "string" || !cs.system.trim()) throw new ConfigError('cardSource.system 必须是对接系统的名称，例如 "ALM"');
@@ -605,7 +617,7 @@ export interface LoadedConfig {
 }
 
 /** Keys a project file may not set: they run code or reach outside the repository. */
-const NOT_IN_PROJECT_KEYS = ["notifiers", "integrations", "push"] as const;
+const NOT_IN_PROJECT_KEYS = ["notifiers", "integrations", "push", "factory"] as const;
 
 /** Notifier module paths are relative to the file that names them; "~/" is the home directory. */
 function resolveNotifiers(raw: Record<string, unknown>, file: string): Record<string, unknown> {

package/engine/src/factory.ts

@@ -0,0 +1,406 @@
+// The intake process (1.11, ADR 0030): a shared development machine takes cards on its own.
+//
+//   req factory once                 one look: start requirements for new cards, pass replies on
+//   req factory run                  look every factory.pollMinutes until stopped (for a service manager)
+//   req factory start | stop         run it in the background on this machine
+//   req factory status               whether it runs, the last look, cards it could not take
+//   req factory service              how to run it as a system service
+//
+// A card is taken when it is listed by the integration's `list` command for a space (projectId)
+// some registered repository takes (cardSource), and its title starts with one of
+// factory.titleTags. Starting is `req start --from` (beginFromCard); passing replies on is
+// `req card check --all` (checkCards). Files: ~/.req-kit/factory/.
+
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { cardRoutes, findCardEntry, hashText, parseJsonOutput } from "./card.js";
+import { beginFromCard, type CardCmdOptions, cardIntegrations, checkCards } from "./card-cmd.js";
+import { loadConfig } from "./config.js";
+import { type IntegrationConfig, renderArgs, runCommand, type Runner } from "./integrations.js";
+import { defaultConfigPath, ENGINE_DIR, KIT_ROOT, kitHome } from "./locations.js";
+import { isAlive } from "./state.js";
+
+const USAGE = `用法：
+  req factory once      检查一次：为新卡片开始需求，把需求方的新回复转给需求会话
+  req factory run       每隔 factory.pollMinutes 分钟检查一次，直到停止（给系统服务用）
+  req factory start     在后台运行（日志：~/.req-kit/factory/factory.log）
+  req factory stop      停止后台运行
+  req factory status    是否在运行、最近一次检查、没能接的卡片
+  req factory service   说明怎样作为系统服务运行（开机自动启动）`;
+
+export interface ListedCard {
+  id: string;
+  title: string;
+  state: string | null;
+  subsystem: string | null;
+  author: string | null;
+}
+
+interface Skipped {
+  reason: string;
+  /** Title and subsystem when it was skipped: a changed card is tried again. */
+  key: string;
+  at: string;
+}
+
+export interface PollResult {
+  started: string[];
+  skipped: string[];
+  relayed: string[];
+  errors: string[];
+  notes: string[];
+}
+
+export function factoryDir(env: NodeJS.ProcessEnv = process.env): string {
+  return path.join(kitHome(env), "factory");
+}
+
+function readJson<T>(file: string, fallback: T): T {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8")) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(file: string, value: unknown): void {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+}
+
+function at(value: unknown, dotted: string): unknown {
+  let cur = value;
+  for (const part of dotted.split(".").filter(Boolean)) {
+    if (cur === null || typeof cur !== "object") return undefined;
+    cur = (cur as Record<string, unknown>)[part];
+  }
+  return cur;
+}
+
+/** The list in a `list` command's output. */
+export function listItems(parsed: unknown, itemsPath?: string): unknown[] {
+  if (itemsPath) {
+    const v = at(parsed, itemsPath);
+    if (!Array.isArray(v)) throw new Error(`输出中 ${itemsPath} 不是列表（list.items）`);
+    return v;
+  }
+  for (const p of ["data.list", "data.records", "data.items", "data.rows", "data", ""]) {
+    const v = p ? at(parsed, p) : parsed;
+    if (Array.isArray(v)) return v;
+  }
+  throw new Error("输出中没有找到卡片列表，请在 list.items 中写明它的位置（例如 \"data.list\"）");
+}
+
+/** All cards of a space the `list` command returns, page by page. */
+export async function listCards(config: IntegrationConfig, projectId: string, titleTag: string, run: Runner = runCommand): Promise<ListedCard[]> {
+  const list = config.list;
+  if (!list) throw new Error(`${config.name} 没有配置 list（列出卡片的命令）`);
+  const pageSize = list.pageSize ?? 100;
+  const maxPages = list.maxPages ?? 5;
+  const out: ListedCard[] = [];
+  for (let page = 1; page <= maxPages; page++) {
+    const args = renderArgs(list.args, { projectId, page: String(page), pageSize: String(pageSize), titleTag });
+    const result = await run(config.command, args, (config.timeoutSeconds ?? 60) * 1000);
+    if (!result.ok) throw new Error(`列出空间 ${projectId} 的卡片失败：${result.error}`);
+    let parsed: unknown;
+    try {
+      parsed = parseJsonOutput(result.output);
+    } catch (error) {
+      throw new Error(`列出空间 ${projectId} 的卡片：${(error as Error).message}`);
+    }
+    if (at(parsed, "success") === false) throw new Error(`列出空间 ${projectId} 的卡片失败：${String(at(parsed, "message") ?? "success 为 false")}`);
+    const items = listItems(parsed, list.items);
+    const str = (item: unknown, p: string | undefined) => {
+      if (!p) return null;
+      const v = at(item, p);
+      return v === undefined || v === null ? null : String(v);
+    };
+    for (const item of items) {
+      const id = str(item, list.fields.id);
+      const title = str(item, list.fields.title);
+      if (!id || title === null) continue;
+      out.push({ id, title, state: str(item, list.fields.state), subsystem: str(item, list.fields.subsystem), author: str(item, list.fields.author) });
+    }
+    if (items.length < pageSize) break;
+  }
+  return out;
+}
+
+export function hasTitleTag(title: string, tags: string[]): boolean {
+  const t = title.trim().toLowerCase();
+  return tags.some((tag) => t.startsWith(tag.trim().toLowerCase()));
+}
+
+/**
+ * One look. Never throws for one card's or one space's trouble: it is reported and the rest goes on.
+ * Cards that could not be taken are not tried again until the card changes or a day has passed.
+ */
+export async function pollOnce(configPath: string, opts: CardCmdOptions = {}, now = new Date()): Promise<PollResult> {
+  const env = opts.env ?? process.env;
+  const dir = factoryDir(env);
+  fs.mkdirSync(dir, { recursive: true });
+  const result: PollResult = { started: [], skipped: [], relayed: [], errors: [], notes: [] };
+
+  // One look at a time on this machine.
+  const lock = path.join(dir, "poll.lock");
+  try {
+    fs.writeFileSync(lock, String(process.pid), { flag: "wx" });
+  } catch {
+    const holder = Number(fs.readFileSync(lock, "utf8"));
+    if (holder && holder !== process.pid && isAlive(holder)) {
+      result.notes.push(`上一次检查（进程 ${holder}）还没有结束，这次跳过`);
+      return result;
+    }
+    fs.writeFileSync(lock, String(process.pid));
+  }
+
+  try {
+    const config = loadConfig(configPath).config;
+    const tags = config.factory.titleTags;
+    const skippedFile = path.join(dir, "skipped.json");
+    const skipped = readJson<Record<string, Skipped>>(skippedFile, {});
+    const { routes } = cardRoutes(env);
+    let newOnes = 0;
+    const integrations = cardIntegrations(config).filter((i) => i.list);
+    if (integrations.length === 0) result.notes.push("没有配置可以列出卡片的外部系统（integrations 中的 list），只转达回复");
+    for (const integration of integrations) {
+      const spaces = [...new Set(routes.filter((r) => r.system.toLowerCase() === integration.name.toLowerCase() && r.projectId).map((r) => r.projectId!))];
+      if (spaces.length === 0) {
+        result.notes.push(`${integration.name}：本机登记的仓库都没有写空间（cardSource.projectId），不知道去哪里找卡片`);
+        continue;
+      }
+      for (const space of spaces) {
+        let cards: ListedCard[];
+        try {
+          cards = await listCards(integration, space, tags[0], opts.run);
+        } catch (error) {
+          result.errors.push(`${integration.name} 空间 ${space}：${(error as Error).message}`);
+          continue;
+        }
+        for (const card of cards.filter((c) => hasTitleTag(c.title, tags))) {
+          const ref = `${integration.name}:${card.id}`;
+          if (findCardEntry(integration.name, card.id, env)) continue;
+          const key = hashText(`${card.title}\0${card.subsystem ?? ""}`);
+          const before = skipped[ref];
+          if (before && before.key === key && now.getTime() - new Date(before.at).getTime() < 24 * 3600_000) continue;
+          if (newOnes >= config.factory.maxNewPerPoll) {
+            result.notes.push(`这次已开始 ${newOnes} 个需求（factory.maxNewPerPoll），其余的下次再接`);
+            break;
+          }
+          try {
+            const begun = await beginFromCard({ integration, id: card.id, repoArg: null, configPath, opts: { ...opts, out: () => undefined } });
+            if (begun.status === "started") {
+              newOnes += 1;
+              result.started.push(`${ref}「${card.title}」→ ${path.join(begun.repo, begun.featureDir)}`);
+            }
+            delete skipped[ref];
+          } catch (error) {
+            skipped[ref] = { reason: (error as Error).message, key, at: now.toISOString() };
+            result.skipped.push(`${ref}「${card.title}」：${(error as Error).message}`);
+          }
+        }
+      }
+    }
+    writeJson(skippedFile, skipped);
+
+    try {
+      const checked = await checkCards(null, opts, configPath, { skipFinished: true });
+      for (const line of checked.lines) {
+        if (/：没有新内容$/.test(line)) continue;
+        if (/已转给需求会话/.test(line)) result.relayed.push(line);
+        else result.errors.push(line);
+      }
+    } catch (error) {
+      result.errors.push(`转达回复：${(error as Error).message}`);
+    }
+  } catch (error) {
+    result.errors.push((error as Error).message);
+  } finally {
+    fs.rmSync(lock, { force: true });
+  }
+  writeJson(path.join(dir, "status.json"), { lastPollAt: now.toISOString(), pid: process.pid, ...result });
+  return result;
+}
+
+function describe(result: PollResult, now = new Date()): string[] {
+  const stamp = now.toLocaleString("zh-CN", { hour12: false });
+  const lines: string[] = [];
+  for (const s of result.started) lines.push(`[${stamp}] 已开始：${s}`);
+  for (const s of result.relayed) lines.push(`[${stamp}] ${s}`);
+  for (const s of result.skipped) lines.push(`[${stamp}] 没能接：${s}`);
+  for (const s of result.errors) lines.push(`[${stamp}] 出错：${s}`);
+  for (const s of result.notes) lines.push(`[${stamp}] ${s}`);
+  if (lines.length === 0) lines.push(`[${stamp}] 检查完毕，没有新卡片和新回复`);
+  return lines;
+}
+
+function pidFile(env: NodeJS.ProcessEnv): string {
+  return path.join(factoryDir(env), "factory.pid");
+}
+
+function runningPid(env: NodeJS.ProcessEnv): number | null {
+  const pid = Number(readJson<string | number>(pidFile(env), 0));
+  return pid && isAlive(pid) ? pid : null;
+}
+
+async function runLoop(configPath: string, opts: CardCmdOptions): Promise<number> {
+  const env = opts.env ?? process.env;
+  const out = opts.out ?? console.log;
+  const other = runningPid(env);
+  if (other && other !== process.pid) {
+    out(`接单器已经在运行（进程 ${other}）。`);
+    return 1;
+  }
+  writeJson(pidFile(env), process.pid);
+  let stopping = false;
+  let wake: (() => void) | null = null;
+  const stop = () => {
+    stopping = true;
+    wake?.();
+  };
+  process.on("SIGTERM", stop);
+  process.on("SIGINT", stop);
+  const minutes = loadConfig(configPath).config.factory.pollMinutes;
+  out(`[${new Date().toLocaleString("zh-CN", { hour12: false })}] 接单器开始运行，每 ${minutes} 分钟检查一次（进程 ${process.pid}）`);
+  try {
+    while (!stopping) {
+      for (const line of describe(await pollOnce(configPath, opts))) out(line);
+      if (stopping) break;
+      await new Promise<void>((resolve) => {
+        wake = resolve;
+        setTimeout(resolve, minutes * 60_000);
+      });
+    }
+  } finally {
+    if (runningPid(env) === process.pid) fs.rmSync(pidFile(env), { force: true });
+    out(`[${new Date().toLocaleString("zh-CN", { hour12: false })}] 接单器已停止`);
+  }
+  return 0;
+}
+
+function startBackground(configPath: string, opts: CardCmdOptions): number {
+  const env = opts.env ?? process.env;
+  const out = opts.out ?? console.log;
+  const pid = runningPid(env);
+  if (pid) {
+    out(`接单器已经在运行（进程 ${pid}）。`);
+    return 0;
+  }
+  // Fail here, in front of the person, rather than silently in the background.
+  loadConfig(configPath);
+  fs.mkdirSync(factoryDir(env), { recursive: true });
+  const log = path.join(factoryDir(env), "factory.log");
+  const fd = fs.openSync(log, "a");
+  const child = spawn(process.execPath, [...process.execArgv, path.join(ENGINE_DIR, "src", "factory.ts"), "run", "--config", configPath], {
+    detached: true,
+    stdio: ["ignore", fd, fd],
+    env,
+    windowsHide: true,
+  });
+  child.unref();
+  writeJson(pidFile(env), child.pid);
+  out(`接单器已在后台运行（进程 ${child.pid}）。日志：${log}`);
+  out("停止：req factory stop；查看：req factory status");
+  return 0;
+}
+
+function stopBackground(opts: CardCmdOptions): number {
+  const env = opts.env ?? process.env;
+  const out = opts.out ?? console.log;
+  const pid = runningPid(env);
+  if (!pid) {
+    out("接单器没有在运行。");
+    return 0;
+  }
+  process.kill(pid, "SIGTERM");
+  out(`已通知接单器（进程 ${pid}）停止；正在进行的检查会做完再停。`);
+  return 0;
+}
+
+function status(opts: CardCmdOptions): number {
+  const env = opts.env ?? process.env;
+  const out = opts.out ?? console.log;
+  const pid = runningPid(env);
+  out(pid ? `接单器正在运行（进程 ${pid}）。` : "接单器没有在运行。");
+  const last = readJson<(PollResult & { lastPollAt: string }) | null>(path.join(factoryDir(env), "status.json"), null);
+  if (last) {
+    out(`最近一次检查：${new Date(last.lastPollAt).toLocaleString("zh-CN", { hour12: false })}；开始 ${last.started.length} 个需求，转达 ${last.relayed.length} 条回复，${last.errors.length} 个错误。`);
+    for (const e of last.errors) out(`  出错：${e}`);
+    for (const n of last.notes) out(`  ${n}`);
+  }
+  const skipped = readJson<Record<string, Skipped>>(path.join(factoryDir(env), "skipped.json"), {});
+  const entries = Object.entries(skipped);
+  if (entries.length > 0) {
+    out("没能接的卡片（卡片修改后或一天后再试）：");
+    for (const [ref, s] of entries) out(`  ${ref}：${s.reason}`);
+  }
+  out(`日志：${path.join(factoryDir(env), "factory.log")}`);
+  return 0;
+}
+
+function service(configPath: string, opts: CardCmdOptions): number {
+  const out = opts.out ?? console.log;
+  const req = path.join(KIT_ROOT, "bin", "req.mjs");
+  const command = `"${process.execPath}" "${req}" factory run --config "${configPath}"`;
+  if (process.platform === "win32") {
+    out("在 Windows 上作为计划任务运行（登录后自动启动），在管理员 PowerShell 中执行：");
+    out(`  schtasks /Create /TN "req-kit 接单器" /SC ONLOGON /RL LIMITED /TR '${command.replace(/'/g, "''")}'`);
+    out("立即启动：schtasks /Run /TN \"req-kit 接单器\"；停止：schtasks /End /TN \"req-kit 接单器\"");
+  } else {
+    out("在 Linux 上作为 systemd 用户服务运行，把下面的内容保存为 ~/.config/systemd/user/req-kit-factory.service：");
+    out("");
+    out("[Unit]\nDescription=req-kit 接单器\nAfter=network-online.target\n\n[Service]");
+    out(`ExecStart=${command}\nRestart=on-failure\nRestartSec=60\n\n[Install]\nWantedBy=default.target`);
+    out("");
+    out("然后执行：systemctl --user daemon-reload && systemctl --user enable --now req-kit-factory");
+    out("（希望不登录也运行：loginctl enable-linger $USER）。macOS 可以用 launchd 或直接 req factory start。");
+  }
+  out("Paseo daemon 需要同时在运行：接单器通过它创建需求会话。");
+  return 0;
+}
+
+export async function main(argv: string[], opts: CardCmdOptions = {}): Promise<number> {
+  const out = opts.out ?? console.log;
+  const [command, ...rest] = argv;
+  const { values } = parseArgs({ args: rest, options: { config: { type: "string" } }, allowPositionals: false, strict: false });
+  const configPath = typeof values.config === "string" ? path.resolve(values.config) : defaultConfigPath(opts.env);
+  try {
+    switch (command) {
+      case "once": {
+        const result = await pollOnce(configPath, opts);
+        for (const line of describe(result)) out(line);
+        return result.errors.length > 0 ? 1 : 0;
+      }
+      case "run":
+        return await runLoop(configPath, opts);
+      case "start":
+        return startBackground(configPath, opts);
+      case "stop":
+        return stopBackground(opts);
+      case "status":
+        return status(opts);
+      case "service":
+        return service(configPath, opts);
+      default:
+        out(USAGE);
+        return command === undefined || command === "help" || command === "--help" ? 0 : 2;
+    }
+  } catch (error) {
+    console.error(`出错了：${(error as Error).message}`);
+    return 1;
+  }
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(import.meta.filename)) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (error) => {
+      console.error(error);
+      process.exit(1);
+    },
+  );
+}

package/engine/src/integrations.ts

@@ -50,6 +50,13 @@ export interface IntegrationConfig {
   query?: IntegrationAction & { fields: CardQueryFields };
   /** Replaces the card's description (1.10): {description} is the whole new description. */
   describe?: IntegrationAction;
+  /**
+   * Lists cards for the intake process (1.11): {projectId}, {page}, {pageSize} and {titleTag}
+   * can be used. The output is JSON; `items` is where the list is (a dot path; by default the
+   * first array found at data.list, data.records, data.items, data or the top level), `fields`
+   * where each card's values are within an item.
+   */
+  list?: IntegrationAction & { items?: string; pageSize?: number; maxPages?: number; fields: CardListFields };
   /** Fields the requester confirms with the spec (card.json): name → what to fill in, for /req. */
   cardFields?: Record<string, string>;
   /** Values for {field.<name>} placeholders; a project's integrationDefaults[name] adds to these. */
@@ -67,6 +74,15 @@ export interface CardQueryFields {
   url?: string;
 }
 
+/** Where `list` finds each card's values within an item. id and title are required. */
+export interface CardListFields {
+  id: string;
+  title: string;
+  state?: string;
+  subsystem?: string;
+  author?: string;
+}
+
 /** What is known about a requirement's card, in the state file's `external[name]`. */
 export interface ExternalRecord {
   id: string | null;
@@ -96,7 +112,7 @@ export function validateIntegrations(value: unknown): string | null {
     if (names.has(c.name)) return `${at}.name「${c.name}」重复了`;
     names.add(c.name);
     if (typeof c.command !== "string" || !c.command.trim()) return `${at}.command 必须是要运行的命令，例如 "shenbing"`;
-    for (const key of ["create", "status", "query", "describe"] as const) {
+    for (const key of ["create", "status", "query", "describe", "list"] as const) {
       const action = c[key] as Record<string, unknown> | undefined;
       if (action === undefined) continue;
       if (!action || !Array.isArray(action.args) || !action.args.every((a) => typeof a === "string")) return `${at}.${key}.args 必须是字符串数组`;
@@ -123,6 +139,18 @@ export function validateIntegrations(value: unknown): string | null {
         if (typeof v !== "string") return `${at}.query.fields.${k} 必须是字符串`;
       }
     }
+    const list = c.list as Record<string, unknown> | undefined;
+    if (list) {
+      const fields = list.fields as Record<string, unknown> | undefined;
+      if (!fields || typeof fields !== "object") return `${at}.list.fields 必须写明每张卡片各值的位置，例如 { "id": "globalId", "title": "name" }`;
+      for (const k of ["id", "title"]) if (typeof fields[k] !== "string") return `${at}.list.fields.${k} 必须是卡片中的位置，例如 "globalId"`;
+      for (const [k, v] of Object.entries(fields)) {
+        if (!["id", "title", "state", "subsystem", "author"].includes(k)) return `${at}.list.fields 中的 ${k} 不认识（可用：id、title、state、subsystem、author）`;
+        if (typeof v !== "string") return `${at}.list.fields.${k} 必须是字符串`;
+      }
+      if (list.items !== undefined && typeof list.items !== "string") return `${at}.list.items 必须是输出中列表的位置，例如 "data.list"`;
+      for (const k of ["pageSize", "maxPages"]) if (list[k] !== undefined && !(Number.isInteger(list[k]) && (list[k] as number) > 0)) return `${at}.list.${k} 必须是正整数`;
+    }
     if (c.statusMap !== undefined) {
       if (!c.statusMap || typeof c.statusMap !== "object") return `${at}.statusMap 必须是对象`;
       for (const [k, v] of Object.entries(c.statusMap)) {

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.10.0-beta.3",
+  "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.10.0-beta.3",
+  "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",