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

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 [docs/guide/安装与升级.md](docs/guide/安装与升级.md)。
 
+## 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
+
+从卡片开始的需求：按子系统自动选仓库、研发完成后推送分支、统计按需求方汇总。
+
+### 使用者会看到的变化
+
+- **按子系统选仓库**：在仓库中运行 `/req-setup` 时可以写上这个仓库接哪个空间、哪些子系统的卡片（同一子系统有几个仓库时再写标题关键字），并在本机登记。之后 `req start --from ALM:<卡号>` 不用写 `--repo`。`req card route` 查看本机登记的仓库。
+- **推送分支**（默认关闭）：本机或团队配置打开 `push` 后，从卡片开始的需求在研发完成、写好提测说明后推送到 `origin` 的 `req/<卡号简称>` 分支，分支名写进卡片。不强推、不合并。
+- **统计**：运行记录带上需求方和卡号，`req stats --report` 多一节"从卡片开始的需求（按需求方）"，CSV 多 `requester`、`card` 两列。
+
+### 升级须知
+
+- 都是可选的。推送只在 `push.enabled` 为 true、需求是从卡片开始的时候发生，并且只能在本机或团队配置中打开（ADR 0029 记录了这条对"只在本地提交"规则的放宽）。
+- 新增项目配置 `cardSource`、本机文件 `~/.req-kit/card-repos.json`、状态文件可选字段 `pushed`、运行记录可选字段 `requirement.requester` 和 `requirement.source`，格式版本都不变。
+
 ## 1.10.0-beta.2
 
 （1.10.0-beta.1 的发布任务因一个测试的顺序问题失败，没有发布，内容相同，以 beta.2 发布。）

package/bin/req.mjs

@@ -35,6 +35,8 @@ const HELP = `req-kit ${version}（${kitRoot}）
   req card check [<卡号>|--all]  读取需求方在卡片中的回复，转给需求的会话
   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]
@@ -159,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/contracts/state.md

@@ -35,6 +35,7 @@
 | `joint` | array \| null | 可选，1.8.0 起。联合需求（spec 的 `- 联合开发：`）中其他仓库的工作区：`name`（`relatedRepos` 中的名称）、`slug`（步骤键的后缀，如 `implement@backend`）、`sourceRepo`（切出工作区的那份检出）、`repo`（工作区目录）、`workspaceId`、`branch`、`specHash`（最近一次同步过去的 spec），以及这个仓库自己的 `codeBase` 和 `gate`（格式同顶层）。见 ADR 0025 |
 | `approval` | object \| null | 可选，1.8.0 起。方案确认点：`attempt`（哪一次尝试的方案）、`status`（`waiting` / `approved`）、`at`。需求变更后的新尝试需要重新确认 |
 | `external` | object \| null | 可选，1.9.0 起。外部系统中的卡片，按集成名称：`id`（卡片编号）、`url`、`status`（最近设置的状态）、`syncedAt`、`pending`（没有成功、等待补发的调用：`action` 为 `create` / `status`、`event`、`status`、`at`、`attempts`、`error`）。见 ADR 0028 |
+| `pushed` | array \| null | 可选，1.10 起。从卡片开始、配置了 `push` 的需求推送过的分支，每个仓库一条（主仓库在前）：`repo`、`remote`、`branch`、`at`、`error`（成功时为 null）。见 ADR 0029 |
 | `gate` | object \| null | 可选，1.8.0 起。质量门：`baseline`（`attempt`、`commit`、`at`、`results`：每项检查改动前 `pass` / `fail`），`runs`（每次运行：`key` 步骤键、`attempt`、`at`、`checks`（`name`、`result`：`pass` / `fail` / `skipped`、`failedBefore`）、`newFailures`、`fixRounds`、`passed`）。各次运行的完整输出在 `.pipeline/checks/<步骤键>/` |
 
 `schedules[].kind` 在 1.7.0 起还可能是 `verify-start`（`--verify-at` 预约的测试验证开始），1.8.0 起还可能是 `approval-continue`（方案确认超时后按方案继续，`designApproval.autoContinueHours`）。`history` 中每条步骤记录在 1.7.0 起有可选的 `phase`（`develop` / `verify`），用于按阶段统计用时与用量；没有时按研发阶段统计。

package/contracts/usage-record.md

@@ -29,7 +29,7 @@
 | --- | --- |
 | `schema` / `kind` | `1` / `"run"` |
 | `machine` / `kitVersion` | 主机名、req-kit 版本 |
-| `requirement` | `{ key, project, name, title, type, profile }` |
+| `requirement` | `{ key, project, name, title, type, profile }`；从卡片开始的需求（1.10 起）另有 `requester`（卡片的提出人）和 `source`（`{ system, id }`） |
 | `run` | `{ startedAt, endedAt, attempt, phase, phaseMode, status, outcome, stopReason }`；`status` 是运行结束时的状态，`outcome` 是完成时报告的结论 |
 | `agents` | `{ builder, reviewer }`：当时配置的 agent（如 `claude/opus（bypassPermissions）`） |
 | `steps` | 这次运行中开始的步骤：`{ key, stepId, phase, attempt, round, startedAt, endedAt, minutes, outcome, inputTokens, outputTokens, costUsd }`；agent 没有报告的用量为 null |

package/docs/adr/0029-requirements-from-cards.md

@@ -30,4 +30,6 @@
 - 新命令：`req start --from`、`req card publish | check | list`。本机新增 `~/.req-kit/cards/`（从卡片开始的需求的登记）。
 - 功能目录新增 `source.json`、`card-source.md`、`card-ai.md`。
 - 运行时新增 `startSessionAgent`：建一个不挂在任何对话下的 agent，工作目录是仓库。
-- beta.3：推送 `req/<卡号>-<简称>` 分支（只对从卡片开始的需求、默认关闭）、`/req-setup` 记录 ALM 空间和子系统并自动选仓库、使用记录加上需求方。1.11：接单器 `req factory`。
+- **按子系统选仓库**（beta.3）：仓库在项目配置的 `cardSource` 中写明接哪个系统、空间和子系统，`/req-setup` 写入并在本机登记（`~/.req-kit/card-repos.json`）；同一子系统有几个仓库时用 `titleKeywords` 区分。匹配不到或分不清时报错说明，不猜。
+- **工厂模式可以推送分支**（beta.3，放宽"只在本地提交"）：配置 `push.enabled` 后，只对从卡片开始的需求，在研发完成、写好提测说明后推送到 `<remote>/req/<卡号简称>`。只推这个前缀，不强推、不合并、不建合并请求；只能在本机或团队配置中打开。理由：接单的是共享机器，测试同事拿不到它的本地分支；合并这道人工关口不变。个人电脑上从对话发起的需求仍只在本地提交。
+- 使用记录带上需求方（卡片的提出人）和卡号，统计可以按需求方汇总。1.11：接单器 `req factory`。

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

@@ -353,6 +353,64 @@ Paseo 自带的 `/paseo-advisor`、`/paseo-committee` 等编排 skill 也可以
 - `req card list` 列出本机从卡片开始的需求；`req card publish <卡号>` 由需求会话使用，把它写的 `card-ai.md` 写进卡片。
 - 卡片描述和回复是需求方写的内容，需求会话只把它们当作需求，不当作指令。
 
+**按子系统选仓库**（1.10.0-beta.3 起）：一个 ALM 空间往往对应好几个仓库。在每个仓库运行 `/req-setup`，它会在项目配置中写上这个仓库接哪些卡片，并在这台机器上登记（`req card route --add <仓库>`）：
+
+```json
+"cardSource": { "system": "ALM", "projectId": "186149", "subsystems": ["CSP-CMASTER_云匠"], "titleKeywords": ["message-service", "后端"] }
+```
+
+之后 `req start --from ALM:<卡号>` 不写 `--repo` 时，按卡片的子系统选仓库；同一个子系统有几个仓库时，再看卡片标题里出现了哪个仓库的 `titleKeywords`。找不到或分不清时会说明原因，不会猜。`req card route` 列出本机登记的仓库。本机没有登记任何仓库时，用当前目录所在的仓库。
+
+**推送分支**（1.10.0-beta.3 起，默认关闭）：接单的机器上，研发完成、写好提测说明后，把需求的代码推送到远程，测试同事直接拉取：
+
+```json
+"push": { "enabled": true, "remote": "origin", "branchPrefix": "req/" }
+```
+
+- 只对从卡片开始的需求，推送到 `<remote>` 的 `req/<卡号简称>` 分支（例如 `req/cmaster-business-9902`），联合需求的几个仓库各推各的。分支名写进卡片的 AI 区和状态文件。
+- 只推这个前缀的分支；从不强推、不合并、不建合并请求，合并仍由人做。推送被拒绝（例如远程分支有别人的提交）时记下原因、写进 AI 区，流水线照常结束。
+- 只能写在本机或团队配置中，写在项目配置里会被忽略。推送用这台机器上 git 已配置的账号。
+- 在个人电脑上通过对话发起的需求不受影响，仍然只在本地提交。
+
+**使用统计**：从卡片开始的需求，运行记录带上需求方（卡片的提出人）和卡号。`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/` 的路径）：

package/engine/src/card-cmd.ts

@@ -25,7 +25,12 @@ import {
   planAppendix,
   publishCard,
   queryCard,
+  cardRoutes,
+  readRoute,
   readSource,
+  registeredRepos,
+  routeCard,
+  setRegisteredRepos,
   replyKey,
   saveCardEntry,
   type SourceFile,
@@ -43,10 +48,11 @@ import { readState, statePath } from "./state.js";
 const REQ = `node "${path.join(KIT_ROOT, "bin", "req.mjs").split(path.sep).join("/")}"`;
 
 const USAGE = `用法：
-  req start --from <系统>:<卡号> [--repo <仓库目录>]   从需求管理系统中的一张卡片开始需求
+  req start --from <系统>:<卡号> [--repo <仓库目录>]   从需求管理系统中的一张卡片开始需求（不写 --repo 时按子系统选仓库）
   req card publish <卡号> [--progress <文字>]           把功能目录中的 card-ai.md 写进卡片的 AI 区
   req card check [<卡号> | --all]                       读取需求方在卡片中的回复，把新内容转给需求的会话
   req card list                                         本机从卡片开始的需求
+  req card route [--add <仓库> | --remove <仓库>]         本机接收卡片的仓库及其子系统（--from 不写 --repo 时按它选仓库）
 
 <卡号> 可以写成 <系统>:<卡号>，例如 ALM:CMASTER-BUSINESS#9902；只配置了一个可以读取卡片的系统时可以省略系统。`;
 
@@ -56,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);
 }
 
@@ -135,62 +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 repo = gitTop(path.resolve(opts.cwd ?? process.cwd(), values.repo ?? "."));
-  const configPath = values.config ? path.resolve(values.config) : defaultConfigPath(opts.env);
-  const config = loadConfig(configPath, repo).config;
-  const { config: integration, id } = parseCardRef(values.from, cardIntegrations(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 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;
 }
@@ -299,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 });
@@ -318,16 +360,60 @@ 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 {
+  const out = opts.out ?? console.log;
+  const { values } = parseArgs({ args: argv, options: { add: { type: "string" }, remove: { type: "string" }, config: { type: "string" } }, allowPositionals: false });
+  const cwd = opts.cwd ?? process.cwd();
+  const configPath = values.config ? path.resolve(values.config) : defaultConfigPath(opts.env);
+  const systems = fs.existsSync(configPath) ? cardIntegrations(loadConfig(configPath).config).map((i) => i.name) : [];
+  if (values.add) {
+    const repo = gitTop(path.resolve(cwd, values.add));
+    const r = readRoute(repo);
+    setRegisteredRepos([...registeredRepos(opts.env), repo], opts.env);
+    out(r ? `已登记 ${repo}：${r.system} 空间 ${r.projectId ?? "（未写）"}，子系统 ${r.subsystems.join("、") || "（未写）"}` : `已登记 ${repo}，但它的项目配置还没有 cardSource（运行 /req-setup 写上）`);
+    return 0;
+  }
+  if (values.remove) {
+    const repo = gitTop(path.resolve(cwd, values.remove));
+    setRegisteredRepos(registeredRepos(opts.env).filter((r) => r !== repo), opts.env);
+    out(`已取消登记 ${repo}`);
+    return 0;
+  }
+  if (systems.length === 0) out("没有配置可以读取卡片的外部系统（本机或团队配置的 integrations 中没有写 query）。");
+  const { routes, missing } = cardRoutes(opts.env);
+  if (routes.length === 0 && missing.length === 0) {
+    out("本机还没有登记接收卡片的仓库：在仓库中运行 /req-setup（或 req card route --add <仓库目录>）。");
+    return 0;
+  }
+  for (const r of routes) out(`${r.system}  空间 ${r.projectId ?? "-"}  子系统 ${r.subsystems.join("、") || "-"}  标题关键字 ${r.titleKeywords.join("、") || "-"}  ${r.repo}`);
+  for (const m of missing) out(`（没有 cardSource 或目录不存在）${m}`);
+  return 0;
 }
 
 function list(opts: CardCmdOptions): number {
@@ -360,6 +446,8 @@ export async function main(argv: string[], opts: CardCmdOptions = {}): Promise<n
       case "list":
       case "ls":
         return list(opts);
+      case "route":
+        return route(rest, opts);
       default:
         console.log(USAGE);
         return command === undefined || command === "help" || command === "--help" ? 0 : 2;

package/engine/src/card.ts

@@ -395,3 +395,87 @@ export function planAppendix(repo: string, featureDir: string): string | null {
   const shown = preview.length > 4000 ? `${preview.slice(0, 4000)}\n\n……（完整内容见功能目录中的 preview.md）` : preview;
   return `### 待确认的方案\n\n${shown.replace(/^(#{1,4})\s/gm, "$1## ")}\n\n确认没问题就在回复区写“方案确认：同意”；要改就在那一行后写明要改什么。`;
 }
+
+// ---------------------------------------------------------------------------
+// Which repository a card belongs to (1.10): each repository says in its project file
+// (cardSource, written by /req-setup) which system, space and subsystems it takes; the
+// machine keeps a list of repositories that take cards (~/.req-kit/card-repos.json).
+
+export interface CardRoute {
+  repo: string;
+  system: string;
+  projectId: string | null;
+  subsystems: string[];
+  titleKeywords: string[];
+}
+
+function cardReposFile(env: NodeJS.ProcessEnv): string {
+  return path.join(kitHome(env), "card-repos.json");
+}
+
+export function registeredRepos(env: NodeJS.ProcessEnv = process.env): string[] {
+  try {
+    const list = JSON.parse(fs.readFileSync(cardReposFile(env), "utf8")) as unknown;
+    return Array.isArray(list) ? list.filter((r): r is string => typeof r === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+export function setRegisteredRepos(repos: string[], env: NodeJS.ProcessEnv = process.env): void {
+  fs.mkdirSync(path.dirname(cardReposFile(env)), { recursive: true });
+  fs.writeFileSync(cardReposFile(env), `${JSON.stringify([...new Set(repos)].sort(), null, 2)}\n`);
+}
+
+/** The repository's cardSource, read from its project file (not merged with other layers). */
+export function readRoute(repo: string): CardRoute | null {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(repo, ".requirement-pipeline.json"), "utf8")) as { cardSource?: Record<string, unknown> };
+    const c = raw.cardSource;
+    if (!c || typeof c.system !== "string") return null;
+    const strings = (v: unknown) => (Array.isArray(v) ? v.filter((x): x is string => typeof x === "string" && x.trim() !== "") : []);
+    return { repo, system: c.system, projectId: c.projectId === undefined || c.projectId === null ? null : String(c.projectId), subsystems: strings(c.subsystems), titleKeywords: strings(c.titleKeywords) };
+  } catch {
+    return null;
+  }
+}
+
+/** Routes of the repositories this machine knows: registered ones, and those cards started in. */
+export function cardRoutes(env: NodeJS.ProcessEnv = process.env): { routes: CardRoute[]; missing: string[] } {
+  const repos = [...new Set([...registeredRepos(env), ...listCardEntries(env).map((e) => e.sourceRepo)])];
+  const routes: CardRoute[] = [];
+  const missing: string[] = [];
+  for (const repo of repos) {
+    const route = fs.existsSync(repo) ? readRoute(repo) : null;
+    if (route) routes.push(route);
+    else missing.push(repo);
+  }
+  return { routes, missing };
+}
+
+const same = (a: string, b: string) => a.trim().toLowerCase() === b.trim().toLowerCase();
+
+/**
+ * The repository for a card: the one whose cardSource names the card's system and subsystem;
+ * when several share the subsystem, the one whose titleKeywords appear in the card's title.
+ * Null when no repository on this machine takes cards (then the caller uses --repo or the
+ * current directory). Throws when repositories take cards but none or several match.
+ */
+export function routeCard(card: Pick<CardData, "id" | "title" | "subsystem">, system: string, env: NodeJS.ProcessEnv = process.env): string | null {
+  const { routes } = cardRoutes(env);
+  const ofSystem = routes.filter((r) => same(r.system, system));
+  if (ofSystem.length === 0) return null;
+  const bySubsystem = card.subsystem ? ofSystem.filter((r) => r.subsystems.some((s) => same(s, card.subsystem!))) : [];
+  if (bySubsystem.length === 0) {
+    throw new Error(
+      `卡片 ${card.id} 的子系统「${card.subsystem ?? "（没有）"}」没有对应的仓库。本机登记的仓库：${ofSystem.map((r) => `${r.repo}（${r.subsystems.join("、") || "未写子系统"}）`).join("；")}。请在对应仓库运行 /req-setup 写上这个子系统，或用 --repo 指定。`,
+    );
+  }
+  if (bySubsystem.length === 1) return bySubsystem[0].repo;
+  const title = card.title.toLowerCase();
+  const byKeyword = bySubsystem.filter((r) => r.titleKeywords.some((k) => title.includes(k.toLowerCase())));
+  if (byKeyword.length === 1) return byKeyword[0].repo;
+  throw new Error(
+    `卡片 ${card.id}「${card.title}」可能属于几个仓库：${(byKeyword.length ? byKeyword : bySubsystem).map((r) => `${r.repo}（标题关键字：${r.titleKeywords.join("、") || "未写"}）`).join("；")}。请在各仓库的 cardSource.titleKeywords 中写上能区分它们的词（例如服务名、"前端""后端"），或用 --repo 指定。`,
+  );
+}

package/engine/src/config.ts

@@ -180,6 +180,24 @@ export interface PipelineConfig {
   integrations: IntegrationConfig[];
   /** Per integration name, values for its {field.*} placeholders; a project's file may set these (e.g. its project id). */
   integrationDefaults: Record<string, Record<string, string>>;
+  /**
+   * Pushing the branch of a requirement that started from a card, once development is done and
+   * the handoff is written (1.10). Off by default; machine or team config only. Never forced,
+   * only to branches under `branchPrefix`, never merged.
+   */
+  push: { enabled: boolean; remote: string; branchPrefix: string };
+  /**
+   * Which cards this repository takes (1.10, written by /req-setup in the project's file): the
+   * system, its space (project id) and subsystems; `titleKeywords` tells apart repositories
+   * 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[] };
   /**
@@ -284,6 +302,9 @@ export const DEFAULT_CONFIG: PipelineConfig = {
   notifiers: [],
   integrations: [],
   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,
@@ -347,6 +368,17 @@ 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 = {
+      system: c.system as string,
+      projectId: c.projectId === undefined || c.projectId === null ? null : String(c.projectId),
+      subsystems: (c.subsystems ?? []) as string[],
+      titleKeywords: (c.titleKeywords ?? []) as string[],
+    };
+  }
   merged.stepTimeoutMinutes = {
     ...base.stepTimeoutMinutes,
     ...(isRecord(raw.stepTimeoutMinutes) ? raw.stepTimeoutMinutes : {}),
@@ -535,6 +567,21 @@ function validate(config: PipelineConfig): void {
   if (!isRecord(config.integrationDefaults) || !Object.values(config.integrationDefaults).every((m) => isRecord(m) && Object.values(m).every((v) => typeof v === "string"))) {
     throw new ConfigError('integrationDefaults 必须是 { "<集成名称>": { "<字段>": "<值>" } }');
   }
+  const push = config.push;
+  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"');
+    for (const k of ["subsystems", "titleKeywords"] as const) {
+      if (!Array.isArray(cs[k]) || !cs[k].every((v) => typeof v === "string" && v.trim())) throw new ConfigError(`cardSource.${k} 必须是字符串数组`);
+    }
+  }
   if (config.requiredVersion !== null && typeof config.requiredVersion !== "string") {
     throw new ConfigError('requiredVersion 必须是版本范围字符串，例如 ">=1.2.0 <2"');
   }
@@ -570,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"] 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> {