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

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/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.11.0-beta.1",
   "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",