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

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 每个版本分为"使用者会看到的变化"和"升级须知"。升级步骤见 [docs/guide/安装与升级.md](docs/guide/安装与升级.md)。
 
+## 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,7 @@ 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 stats [--since 30d] [--month 2026-10]

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/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,27 @@ 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` 两列。
+
 ## 团队配置
 
 几台机器、多个项目共用的设置（统一的模型、评审小组、超时、要求的 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；只配置了一个可以读取卡片的系统时可以省略系统。`;
 
@@ -139,10 +145,9 @@ async function startFromCard(argv: string[], opts: CardCmdOptions): Promise<numb
   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));
+  // 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 existing = findCardEntry(integration.name, id, opts.env);
   if (existing) {
@@ -152,6 +157,11 @@ async function startFromCard(argv: string[], opts: CardCmdOptions): Promise<numb
   }
 
   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 });
@@ -330,6 +340,36 @@ async function check(argv: string[], opts: CardCmdOptions): Promise<number> {
   return 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 {
   const out = opts.out ?? console.log;
   const entries = listCardEntries(opts.env);
@@ -360,6 +400,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,18 @@ 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;
   /** Automatic retries of a step after a transient error (rate limit, dropped connection). */
   retry: { attempts: number; backoffSeconds: number[] };
   /**
@@ -284,6 +296,8 @@ export const DEFAULT_CONFIG: PipelineConfig = {
   notifiers: [],
   integrations: [],
   integrationDefaults: {},
+  push: { enabled: false, remote: "origin", branchPrefix: "req/" },
+  cardSource: null,
   retry: { attempts: 2, backoffSeconds: [60, 300] },
   paseoServices: "auto",
   serviceReadySeconds: 120,
@@ -347,6 +361,16 @@ function merge(base: PipelineConfig, raw: Record<string, unknown>): PipelineConf
     }
     merged.integrationDefaults = combined;
   }
+  merged.push = { ...base.push, ...(isRecord(raw.push) ? raw.push : {}) } as PipelineConfig["push"];
+  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 +559,17 @@ 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 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 +605,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"] 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/pipeline.ts

@@ -34,7 +34,7 @@ import { kitVersion } from "./locations.js";
 import { type AgentUsage, describeTotals, totals } from "./usage.js";
 import { dispatchNotifiers, type NotifierEventType } from "./notifiers.js";
 import { describeExternal, type IntegrationEvent, type Runner, syncIntegration } from "./integrations.js";
-import { planAppendix, publishCard, readSource } from "./card.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 CheckOutcome, type GateRun, type JointRepo, type PhaseName, type PipelineState, type RunPhases, type StepRecord, writeState } from "./state.js";
@@ -414,6 +414,40 @@ const CARD_PROGRESS: Record<IntegrationEvent, string> = {
   failed: "流水线中断，正在处理",
 };
 
+/**
+ * A requirement that started from a card (1.10), with `push` on: once development is done and the
+ * handoff is written, pushes each repository's branch to <remote>/<prefix><card>. Never forced
+ * (a rejected push is reported, not retried with force), never merged. Never throws.
+ */
+function pushBranch(ctx: PipelineContext): void {
+  const push = ctx.config.push;
+  if (!push.enabled) return;
+  const source = readSource(ctx.repo, ctx.featureDir);
+  if (!source) return;
+  const branch = `${push.branchPrefix}${cardSlug(source.id)}`;
+  const repos = [ctx.repo, ...(ctx.state.joint ?? []).map((j) => j.repo)];
+  const at = new Date().toISOString();
+  for (const repo of repos) {
+    let error: string | null = null;
+    try {
+      execFileSync("git", ["push", push.remote, `HEAD:refs/heads/${branch}`], { cwd: repo, stdio: ["ignore", "pipe", "pipe"], timeout: 180_000, windowsHide: true });
+    } catch (e) {
+      const stderr = (e as { stderr?: Buffer | string }).stderr?.toString().trim();
+      error = (stderr || (e as Error).message).split("\n").filter(Boolean).slice(-2).join(" ");
+    }
+    ctx.state.pushed = [...(ctx.state.pushed ?? []).filter((p) => p.repo !== repo), { repo, remote: push.remote, branch, at, error }];
+    ctx.log(error ? `推送 ${repo} 的分支到 ${push.remote}/${branch} 失败：${error}` : `已推送 ${repo} 的分支到 ${push.remote}/${branch}`);
+  }
+  save(ctx);
+}
+
+/** Where the requirement's code is, for the card: the pushed branch, or the local one. */
+function branchText(ctx: PipelineContext): string | null {
+  const mine = ctx.state.pushed?.find((p) => p.repo === ctx.repo);
+  if (mine) return mine.error ? `分支 ${ctx.state.branch}（推送到 ${mine.remote}/${mine.branch} 失败：${mine.error}）` : `代码已推送到 ${mine.remote} 的分支 ${mine.branch}`;
+  return ctx.state.branch ? `分支 ${ctx.state.branch}` : null;
+}
+
 /** A requirement that started from a card (1.10): its AI section follows the pipeline. Never throws. */
 async function updateCard(ctx: PipelineContext, event: IntegrationEvent): Promise<void> {
   const source = readSource(ctx.repo, ctx.featureDir);
@@ -422,7 +456,7 @@ async function updateCard(ctx: PipelineContext, event: IntegrationEvent): Promis
   if (!config?.describe || !config.query) return;
   const approval = event === "approval";
   let progress = CARD_PROGRESS[event];
-  if (event === "phase_done" && ctx.state.branch) progress += `，分支 ${ctx.state.branch}`;
+  if (event === "phase_done" && branchText(ctx)) progress += `，${branchText(ctx)}`;
   if (event === "completed" && ctx.state.outcome && ctx.state.outcome !== "completed") progress = `已结束（${ctx.state.outcome === "completed_with_issues" ? "有遗留问题，见完成报告" : "没有完成，见完成报告"}）`;
   try {
     await publishCard({
@@ -1795,6 +1829,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
       ? `研发已完成（只做研发）：${outcomeText[report.outcome as string] ?? report.outcome}，请按提测说明人工测试。`
       : `开发流水线已结束：${outcomeText[report.outcome as string] ?? report.outcome}。`;
     // Develop-only ends where testing by people begins: for the card that is "研发完成，待测试".
+    if (developOnly && report.outcome !== "not_completed") pushBranch(ctx);
     await integrate(ctx, developOnly && report.outcome !== "not_completed" ? "phase_done" : "completed");
     await notifyExternal(ctx, "completed", text, {
       outcome: report.outcome,
@@ -1823,6 +1858,7 @@ export async function runPipeline(ctx: PipelineContext): Promise<PipelineOutcome
           handbacks: ctx.state.handbacks ?? 0,
         }),
       );
+      pushBranch(ctx);
       await integrate(ctx, "phase_done");
       await notifyExternal(ctx, "phase_done", `研发已完成，可以提测：提测说明在 ${ctx.featureDir}/handoff.md。${verifyAt ? `已预约在 ${verifyAt} 开始测试验证。` : ""}`, {
         handoffPath: `${ctx.featureDir}/handoff.md`,

package/engine/src/records.ts

@@ -149,6 +149,10 @@ export interface RunRecord {
     title: string;
     type: string | null;
     profile: string;
+    /** Who asked for it: the card's author for a requirement that started from a card (1.10). */
+    requester?: string | null;
+    /** The card it started from, e.g. { system: "ALM", id: "…" } (1.10). */
+    source?: { system: string; id: string } | null;
   };
   run: {
     startedAt: string;
@@ -226,6 +230,7 @@ export function runRecord(input: {
       title: input.title,
       type: state.type ?? null,
       profile: state.profile,
+      ...cardOrigin(state.repo, state.featureDir),
     },
     run: {
       startedAt: input.runStartedAt,
@@ -243,6 +248,17 @@ export function runRecord(input: {
   };
 }
 
+/** The card a requirement started from (source.json), for the record. */
+function cardOrigin(repo: string, featureDir: string): { requester: string | null; source: { system: string; id: string } } | Record<string, never> {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(repo, featureDir, "source.json"), "utf8")) as { system?: unknown; id?: unknown; author?: unknown };
+    if (typeof raw.system !== "string" || typeof raw.id !== "string") return {};
+    return { requester: typeof raw.author === "string" ? raw.author : null, source: { system: raw.system, id: raw.id } };
+  } catch {
+    return {};
+  }
+}
+
 /** Appends a run record. Never throws. */
 export function appendRun(record: RunRecord, env: NodeJS.ProcessEnv = process.env): void {
   if (recordingOff(env)) return;

package/engine/src/state.ts

@@ -109,6 +109,11 @@ export interface PipelineState {
   gate?: { baseline: GateBaseline | null; runs: GateRun[] } | null;
   /** External systems (1.9): the requirement's card in each, by integration name. */
   external?: Record<string, ExternalRecord> | null;
+  /**
+   * Branches pushed for a requirement that started from a card (1.10, `push` config): one entry
+   * per repository (the main one, then joint ones), the latest attempt. `error` is null when it worked.
+   */
+  pushed?: Array<{ repo: string; remote: string; branch: string; at: string; error: string | null }> | null;
 }
 
 export interface JointRepo {

package/engine/src/stats.ts

@@ -87,6 +87,10 @@ export interface RequirementStats {
   waits: Record<WaitKind, number>;
   builder: string | null;
   reviewer: string | null;
+  /** The card's author, for requirements that started from a card (1.10). */
+  requester: string | null;
+  /** "<system>:<id>" of that card. */
+  card: string | null;
 }
 
 function add(a: number | null, b: number | null): number | null {
@@ -162,6 +166,8 @@ export function byRequirement(runs: RunRecord[]): RequirementStats[] {
       waits,
       builder: last.agents.builder,
       reviewer: last.agents.reviewer,
+      requester: last.requirement.requester ?? null,
+      card: last.requirement.source ? `${last.requirement.source.system}:${last.requirement.source.id}` : null,
     });
   }
   return out.sort((a, b) => b.lastEndedAt.localeCompare(a.lastEndedAt));
@@ -202,6 +208,8 @@ export interface StatsSummary {
   waits: Array<{ kind: WaitKind; label: string; requirements: number; averageMinutes: number }>;
   usage: { agentMinutes: number; inputTokens: number | null; outputTokens: number | null; costUsd: number | null };
   byBuilder: Array<{ builder: string; requirements: number; averageReviewRounds: number | null; averageCostUsd: number | null }>;
+  /** Requirements that started from cards, by who asked for them (1.10); empty when there are none. */
+  byRequester: Array<{ requester: string; requirements: number; completed: number; medianCycleHours: number | null }>;
   requirements: RequirementStats[];
 }
 
@@ -246,6 +254,9 @@ export function summarizeRuns(all: RunRecord[], period: Period): StatsSummary {
   const builders = new Map<string, RequirementStats[]>();
   for (const q of done) builders.set(q.builder ?? "（未记录）", [...(builders.get(q.builder ?? "（未记录）") ?? []), q]);
 
+  const requesters = new Map<string, RequirementStats[]>();
+  for (const q of active) if (q.card) requesters.set(q.requester ?? "（未记录）", [...(requesters.get(q.requester ?? "（未记录）") ?? []), q]);
+
   return {
     schema: 1,
     period: { from: period.from?.toISOString() ?? null, to: period.to?.toISOString() ?? null, label: period.label },
@@ -276,6 +287,12 @@ export function summarizeRuns(all: RunRecord[], period: Period): StatsSummary {
       averageReviewRounds: avg(qs.map((q) => q.reviewRounds)),
       averageCostUsd: avg(qs.flatMap((q) => (q.costUsd === null ? [] : [q.costUsd]))),
     })),
+    byRequester: [...requesters.entries()]
+      .map(([requester, qs]) => {
+        const finished = qs.filter((q) => done.includes(q));
+        return { requester, requirements: qs.length, completed: finished.length, medianCycleHours: median(finished.flatMap((q) => (q.cycleHours === null ? [] : [q.cycleHours]))) };
+      })
+      .sort((a, b) => b.requirements - a.requirements || a.requester.localeCompare(b.requester)),
     requirements: active,
   };
 }
@@ -342,6 +359,10 @@ export function describeStats(s: StatsSummary): string {
     lines.push("", "## 按 builder 比较（已完成的需求）", "", "| builder | 需求数 | 平均评审轮数 | 平均费用 |", "| --- | --- | --- | --- |");
     for (const b of s.byBuilder) lines.push(`| ${b.builder} | ${b.requirements} | ${b.averageReviewRounds ?? "-"} | ${b.averageCostUsd === null ? "-" : `$${b.averageCostUsd.toFixed(2)}`} |`);
   }
+  if (s.byRequester.length > 0) {
+    lines.push("", "## 从卡片开始的需求（按需求方）", "", "| 需求方 | 需求数 | 已完成 | 周期中位数 |", "| --- | --- | --- | --- |");
+    for (const r of s.byRequester) lines.push(`| ${r.requester} | ${r.requirements} | ${r.completed} | ${r.medianCycleHours === null ? "-" : `${r.medianCycleHours} 小时`} |`);
+  }
   lines.push("", "## 需求", "", "| 项目 | 需求 | 类型 | 状态 | 周期 | agent 用时 | 评审轮数 | 缺陷轮数 |", "| --- | --- | --- | --- | --- | --- | --- | --- |");
   for (const q of s.requirements) {
     const status = q.status === "completed" ? (OUTCOME_LABELS[q.outcome ?? "unknown"] ?? "已完成") : (STATUS_LABELS[q.status] ?? q.status);
@@ -378,6 +399,8 @@ const CSV_COLUMNS: Array<[string, (q: RequirementStats) => unknown]> = [
   ["wait_verify_minutes", (q) => q.waits.verify],
   ["builder", (q) => q.builder ?? ""],
   ["reviewer", (q) => q.reviewer ?? ""],
+  ["requester", (q) => q.requester ?? ""],
+  ["card", (q) => q.card ?? ""],
 ];
 
 function csvCell(v: unknown): string {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paseo-req-kit",
-  "version": "1.10.0-beta.2",
+  "version": "1.10.0-beta.3",
   "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.2",
+  "version": "1.10.0-beta.3",
   "private": true,
   "description": "The req-kit plugin for Paseo. Ships inside the paseo-req-kit package; installed with req plugin install.",
   "type": "module",

package/skills/req-setup/SKILL.md

@@ -60,6 +60,7 @@ metadata:
 - 有没有相关的其他仓库（例如这是前端，接口在另一个后端仓库）：在这台机器上的位置、它提供什么。登记后流水线的步骤可以只读参考它，不会改动它
 - 多模块的仓库（例如 `web/` 和 `server/` 各有自己的测试）：确认各模块的检查命令，第 5 步按模块写进 `checks`
 - 项目已经有 `paseo.json` 时，要不要由你补充；没有时，要不要生成（推荐生成，见第 5 步）
+- **从卡片接需求**（团队对接了需求管理系统时）：先执行 `node "{{REQ_KIT_ROOT}}/bin/req.mjs" card route`。输出"没有配置可以读取卡片的外部系统"或团队不用卡片开始需求时跳过；否则问：这个仓库属于需求管理系统中的哪个空间（项目编号，如 ALM 的 projectId）、接哪些子系统的卡片（卡片上显示的子系统名称，可以多个）；同一个子系统还有别的仓库时（例如前端和后端各一个），卡片标题中用什么词区分（例如服务名"message-service"、"后端"）。第 5 步写进 `cardSource`
 
 ## 4. 实际运行验证命令
 
@@ -106,6 +107,7 @@ metadata:
     }
     ```
   - `relatedRepos`（有关联仓库时）：`[{ "name": "后端", "path": "../backend", "role": "提供登录和订单接口" }]`。`path` 写相对项目目录的路径（团队约定把相关仓库放在同一个上级目录最方便），也可以写 `~/` 开头的路径。平时流水线的步骤只读不改；需求说明写了"联合开发"时，流水线会为这个需求在它那里新建工作区，一起开发。关联仓库最好也运行过 `/req-setup`，它自己的检查命令、验证方法和项目说明会用在它的步骤里。
+  - `cardSource`（第 3 步确认了从卡片接需求时）：`{ "system": "ALM", "projectId": "186149", "subsystems": ["CSP-CMASTER_云匠"], "titleKeywords": ["message-service"] }`。`system` 是团队对接配置中的系统名称；`titleKeywords` 只在同一子系统有几个仓库时写。之后 `req start --from` 不写仓库时，按卡片的子系统和标题选到这个仓库
   - 其他设置只在需要和本机配置不同时才写，例如 `"defaultProfile": "quick"`。不要写 `daemonUrl`、`daemonPasswordEnv`、`teamConfig`，写了也会被忽略。
 - `.gitignore`：确认包含 `docs/features/*/.pipeline/`（流水线的运行状态），没有就建议加上。
 
@@ -115,4 +117,6 @@ metadata:
 
 用户确认后，只提交这几个文件（以及 `GLOSSARY.md`、`scripts/paseo/` 和 `.gitignore` 的改动）。`paseo.json` 必须提交：Paseo 新建 worktree 时读取的是基准分支上已提交的版本，提交信息例如 `chore(req-kit): 项目接入说明与验证方法`。不 push。
 
+写了 `cardSource` 的，提交后执行 `node "{{REQ_KIT_ROOT}}/bin/req.mjs" card route --add .`，在这台机器上登记这个仓库接收卡片（每台接单的机器各登记一次）。
+
 最后告诉用户：之后项目的构建、测试或启动方式有变化时，再运行一次 `/req-setup`；也可以直接编辑这些文件。可以运行 `/req-doctor` 确认项目检查全部正常。