paseo-req-kit 1.12.0-beta.2 → 1.12.0-beta.4

package/engine/src/config-view.ts

@@ -0,0 +1,289 @@
+// The whole req-kit configuration as people read it (1.12, `req api config`, the plugin's
+// settings view): every setting with a plain name, what it does, its value in words, and which
+// file set it (default, this machine, the team, the project). Secrets are never shown.
+
+import fs from "node:fs";
+import path from "node:path";
+import {
+  type AgentProfile,
+  DEFAULT_CONFIG,
+  loadConfig,
+  MACHINE_ONLY_KEYS,
+  NOT_IN_PROJECT_KEYS,
+  PHASE_MODE_LABELS,
+  type PipelineConfig,
+  PROFILE_LABELS,
+  PROJECT_CONFIG_FILE,
+} from "./config.js";
+import { describeAgentProfile } from "./paseo-profiles.js";
+import { STEPS, type StepId } from "./steps.js";
+
+export type Layer = "default" | "machine" | "team" | "project";
+
+export const LAYER_LABELS: Record<Layer, string> = { default: "默认", machine: "本机", team: "团队", project: "项目" };
+
+export interface ConfigItem {
+  key: string;
+  label: string;
+  description: string;
+  /** The value in words. */
+  display: string;
+  /** The value itself, secrets masked. */
+  value: unknown;
+  /** The files that set it, in the order they apply; empty when it is the default. */
+  setBy: Exclude<Layer, "default">[];
+  /** Where it may be set: machine-only settings are ignored in team and project files. */
+  scope: "any" | "machine" | "machine_team";
+  /** Whether the value differs from req-kit's default (a file may repeat the default). */
+  changed: boolean;
+}
+
+export interface ConfigGroup {
+  id: string;
+  title: string;
+  description: string;
+  items: ConfigItem[];
+}
+
+export interface ConfigView {
+  sources: Array<{ layer: Exclude<Layer, "default">; path: string }>;
+  /** Settings a team or project file may not set, which were left out. */
+  ignored: string[];
+  /** The configuration does not load; the values shown are the files' as written. */
+  error: string | null;
+  repo: string | null;
+  groups: ConfigGroup[];
+}
+
+const onOff = (v: unknown) => (v ? "开" : "关");
+const minutes = (v: unknown) => (Number(v) > 0 ? `${v} 分钟` : "关闭");
+const hours = (v: unknown) => (Number(v) > 0 ? `${v} 小时` : "关闭");
+const list = (v: unknown) => (Array.isArray(v) && v.length > 0 ? v.join("、") : "无");
+const profilesText = (v: unknown) => (Array.isArray(v) ? v.map((p) => PROFILE_LABELS[p as "quick"] ?? p).join("、") + "档" : String(v));
+
+function agent(p: AgentProfile | null | undefined): string {
+  return p ? describeAgentProfile(p) : "未设置";
+}
+
+interface Entry {
+  label: string;
+  description: string;
+  display?: (value: unknown, config: PipelineConfig) => string;
+}
+
+/** Groups in the order people look for them; a key not listed here goes to "其他". */
+const CATALOG: Array<{ id: string; title: string; description: string; keys: Record<string, Entry> }> = [
+  {
+    id: "agents",
+    title: "模型与评审",
+    description: "谁来写代码、谁来评审，以及评审有多严格。",
+    keys: {
+      agents: {
+        label: "agent",
+        description: "builder 做方案、写代码和修复；reviewer 审方案、评审代码和验证；备用模型在主模型一直失败时接手一步。",
+        display: (v) => {
+          const a = v as PipelineConfig["agents"];
+          return `builder：${agent(a.builder)}；reviewer：${agent(a.reviewer)}；备用模型：${a.fallback ? agent(a.fallback) : "不用"}`;
+        },
+      },
+      defaultProfile: { label: "默认档位", description: "需求说明没写档位时用哪个。", display: (v) => `${PROFILE_LABELS[v as "quick"] ?? v}档` },
+      profiles: {
+        label: "各档位的轮数",
+        description: "方案审核、代码评审、缺陷修复最多几轮，以及是否先验证服务能启动。",
+        display: (v) =>
+          Object.entries(v as PipelineConfig["profiles"])
+            .map(([name, p]) => `${PROFILE_LABELS[name as "quick"] ?? name}档：方案审核 ${p.rounds.designReview} 轮、代码评审 ${p.rounds.codeReview} 轮、缺陷修复 ${p.rounds.defectFix} 轮${p.serviceStart ? "、验证服务启动" : ""}`)
+            .join("；"),
+      },
+      reviewAxes: { label: "分方向评审", description: "代码评审分“规格”和“规范”两个方向各看一遍。", display: (v) => { const r = v as PipelineConfig["reviewAxes"]; return r.enabled ? `开（${profilesText(r.profiles)}）` : "关"; } },
+      reviewPanel: { label: "评审小组", description: "几个模型同时评审，再汇总。", display: (v) => { const r = v as PipelineConfig["reviewPanel"]; return r.enabled ? `${r.members.length} 位成员，用于${r.steps.map((s) => STEPS[s as StepId]?.title ?? s).join("、")}（${profilesText(r.profiles)}）` : "关"; } },
+      designProposals: { label: "方案提案", description: "方案设计前先让几个模型各出一份提案。", display: (v) => { const r = v as PipelineConfig["designProposals"]; return r.enabled ? `开（${profilesText(r.profiles)}${r.members.length ? `，${r.members.length} 位成员` : ""}）` : "关"; } },
+    },
+  },
+  {
+    id: "flow",
+    title: "流程",
+    description: "需求按什么顺序走、在哪里停下等人。",
+    keys: {
+      phases: {
+        label: "执行方式",
+        description: "研发完成后接着测试验证，还是停下等测试，或只做研发。",
+        display: (v) => { const p = v as PipelineConfig["phases"]; return `${PHASE_MODE_LABELS[p.mode]}；测试验证在${p.verify.environment === "deployed" ? "已部署的测试环境" : "本地"}；发现缺陷时${p.verify.defects === "fix" ? "直接修复" : p.verify.defects === "handback" ? "退回研发阶段" : "只记录"}`; },
+      },
+      designApproval: { label: "方案确认点", description: "写代码前请需求方确认“做完后会看到什么”。", display: (v) => { const d = v as PipelineConfig["designApproval"]; return d.mode === "off" ? "关" : `${d.mode === "always" ? "总是" : "有界面改动时"}（${profilesText(d.profiles)}）${d.autoContinueHours > 0 ? `，${d.autoContinueHours} 小时没回应按方案继续` : "，一直等确认"}`; } },
+      specReview: { label: "需求说明审阅", description: "开发前由另一个模型审一遍需求说明。", display: (v) => ({ off: "关", standard: "标准档", always: "所有档位" })[String(v)] ?? String(v) },
+      requirementTypes: { label: "按类型的做法", description: "缺陷、重构、评估各走自己的做法。", display: (v) => list((v as string[]).map((t) => ({ defect: "缺陷", refactor: "重构", assessment: "评估" })[t] ?? t)) },
+      slices: { label: "按切片实现", description: "方案分几片时逐片实现。", display: (v) => { const s = v as PipelineConfig["slices"]; return `${profilesText(s.profiles)}，最多 ${s.max} 片`; } },
+      browserVerify: { label: "用浏览器验证", description: "Paseo 有内置浏览器时，验证网页界面。", display: (v) => ({ auto: "自动", off: "关" })[String(v)] ?? String(v) },
+      paseoServices: { label: "由 Paseo 启动服务", description: "用 paseo.json 中的服务脚本启动和重启服务。", display: (v) => ({ auto: "自动", off: "关" })[String(v)] ?? String(v) },
+      serviceReadySeconds: { label: "等服务就绪", description: "启动服务后最多等多久。", display: (v) => `${v} 秒` },
+    },
+  },
+  {
+    id: "quality",
+    title: "质量",
+    description: "流水线自己运行的检查，以及可以参考的其他仓库。",
+    keys: {
+      checks: { label: "质量门的检查", description: "写代码和修复后，流水线自己运行这些命令，比较改动前后。通常由 /req-setup 写在项目配置中。", display: (v) => (Array.isArray(v) && v.length > 0 ? (v as Array<{ name: string; command: string }>).map((c) => `${c.name}（${c.command}）`).join("、") : "没有（不运行质量门）") },
+      qualityGate: { label: "质量门的修复", description: "检查发现新失败时，同一个 agent 修几次；每项检查的时限。", display: (v) => { const q = v as PipelineConfig["qualityGate"]; return `最多修 ${q.fixAttempts} 次，每项 ${q.timeoutMinutes} 分钟`; } },
+      relatedRepos: { label: "关联仓库", description: "步骤 agent 可以读、不会修改的其他仓库（例如前端项目的后端）。", display: (v) => (Array.isArray(v) && v.length > 0 ? (v as Array<{ name: string; path: string }>).map((r) => `${r.name}（${r.path}）`).join("、") : "无") },
+    },
+  },
+  {
+    id: "automation",
+    title: "自动处理与时限",
+    description: "出了问题时流水线自己怎么处理，什么时候才停下等人。",
+    keys: {
+      selfHeal: { label: "自愈", description: "超时时 agent 还在做就多等一轮；agent 报错、结果文件无效时新开 agent 重做一次。", display: onOff },
+      answerQuestionsFirst: { label: "方案审核的问题先自答", description: "审核要需求方决定的问题，先由 builder 从代码和文档中找答案。", display: onOff },
+      retry: { label: "临时错误重试", description: "限流、网络中断时换一个 agent 重做这一步。", display: (v) => { const r = v as PipelineConfig["retry"]; return r.attempts > 0 ? `${r.attempts} 次，分别等 ${r.backoffSeconds.join("、")} 秒` : "关"; } },
+      autoResumeMinutes: { label: "自动继续", description: "临时错误中断后，多久自动继续（限流时按额度恢复时间）。", display: minutes },
+      autoResumeMax: { label: "自动继续的次数", description: "每次尝试最多自动继续几次。", display: (v) => `${v} 次` },
+      watchdogMinutes: { label: "定时检查", description: "运行期间定时检查，后台进程意外退出时自动继续。", display: (v) => (Number(v) > 0 ? `每 ${v} 分钟` : "关闭") },
+      stepTimeoutMinutes: {
+        label: "各步骤的时限",
+        description: "超过时限仍未完成就中断（打开自愈时先多等一轮）。",
+        display: (v) =>
+          Object.entries(v as Record<string, number>)
+            .filter(([id]) => STEPS[id as StepId])
+            .map(([id, m]) => `${STEPS[id as StepId].title} ${m} 分钟`)
+            .join("、"),
+      },
+      resultFollowUps: { label: "提醒补写结果", description: "结果文件缺失或格式不对时，提醒 agent 几次。", display: (v) => `${v} 次` },
+      quotaWarnPercent: { label: "额度提醒", description: "开始时额度用到这么多就提醒。", display: (v) => (Number(v) > 0 ? `${v}%` : "关闭") },
+      waitingReminderHours: { label: "等待提醒", description: "等需求方回答或等测试超过这么久，提醒一次。", display: hours },
+      maxConcurrentPipelines: { label: "同时运行的上限", description: "本机同时运行的流水线数，满了排队。", display: (v) => (Number(v) > 0 ? `${v} 个` : "不限") },
+      queuePollSeconds: { label: "排队检查间隔", description: "排队时多久看一次有没有空位。", display: (v) => `${v} 秒` },
+    },
+  },
+  {
+    id: "cards",
+    title: "卡片与接单器",
+    description: "和需求管理系统的对接、从卡片开始的需求，以及共享机器上的接单器。",
+    keys: {
+      integrations: { label: "对接的外部系统", description: "用命令读写需求管理系统中的卡片。", display: (v) => (Array.isArray(v) && v.length > 0 ? (v as Array<{ name: string; command: string } & Record<string, unknown>>).map((i) => `${i.name}（${i.command}；${["create", "status", "query", "describe", "list"].filter((k) => i[k]).join("、")}）`).join("；") : "无") },
+      integrationDefaults: { label: "对接字段的默认值", description: "按系统填卡片字段的固定值（例如项目编号）。", display: (v) => { const n = Object.keys(v as object).length; return n > 0 ? `${n} 个系统` : "无"; } },
+      cardSource: { label: "这个仓库接哪些卡片", description: "系统、空间和子系统，由 /req-setup 写在项目配置中。", display: (v) => { if (!v) return "未设置"; const c = v as NonNullable<PipelineConfig["cardSource"]>; return `${c.system}${c.projectId ? ` 空间 ${c.projectId}` : ""}；子系统 ${list(c.subsystems)}${c.titleKeywords.length ? `；标题关键字 ${list(c.titleKeywords)}` : ""}`; } },
+      push: { label: "推送分支", description: "从卡片开始的需求研发完成后，推送到 req/ 前缀的分支（可以再建草稿合并请求）。不强推、不合并。", display: (v) => { const p = v as PipelineConfig["push"]; return p.enabled ? `推送到 ${p.remote}/${p.branchPrefix}<卡号>${p.mergeRequest ? `，用 ${p.mergeRequest.command} 建草稿合并请求` : ""}` : "关"; } },
+      factory: { label: "接单器", description: "多久检查一次、认哪些标题标识、每次最多接几张。", display: (v) => { const f = v as PipelineConfig["factory"]; return `每 ${f.pollMinutes} 分钟；标识 ${list(f.titleTags)}；每次最多 ${f.maxNewPerPoll} 个`; } },
+      autoConfirm: { label: "小改动自动确认", description: "快速档、没有待答问题的卡片，过这么久没有异议就开始。", display: (v) => hours((v as PipelineConfig["autoConfirm"]).hours) },
+    },
+  },
+  {
+    id: "notify",
+    title: "通知",
+    description: "进展和需要人的事发到哪里、发给谁。",
+    keys: {
+      notifyMilestones: { label: "进展通知", description: "方案定了、开始验证等关键点在对话里说一句。", display: onOff },
+      notifiers: { label: "外部通知", description: "额外调用的通知模块（例如内部 IM）。", display: (v) => (Array.isArray(v) && v.length > 0 ? (v as Array<{ module: string; events?: string[] }>).map((n) => `${path.basename(n.module)}（${n.events ? n.events.join("、") : "全部事件"}）`).join("；") : "无") },
+      people: { label: "按人通知的账号", description: "需求方姓名对应的 IM 账号，通知模块按人发送时用。", display: (v) => { const n = Object.keys(v as object).length; return n > 0 ? `${n} 人` : "无"; } },
+    },
+  },
+  {
+    id: "machine",
+    title: "连接与运行",
+    description: "这台机器怎么连 Paseo，以及步骤 agent 怎么创建。",
+    keys: {
+      daemonUrl: { label: "Paseo 地址", description: "本机 Paseo daemon 的地址。" },
+      daemonPasswordEnv: { label: "Paseo 密码的环境变量", description: "daemon 设置了密码时，从这个环境变量读取（这里只显示变量名）。" },
+      teamConfig: { label: "团队配置", description: "团队共用的配置文件。", display: (v) => (v ? String(v) : "未使用") },
+      requiredVersion: { label: "版本要求", description: "团队或项目要求的 req-kit 版本范围。", display: (v) => (v ? String(v) : "无") },
+      attachToOriginChat: { label: "步骤挂在发起的对话下", description: "步骤 agent 作为子 agent 显示在发起的对话中。", display: onOff },
+      archiveStepAgents: { label: "完成后归档步骤", description: "步骤完成后把它的 agent 归档。", display: onOff },
+      waitChunkSeconds: { label: "等待分段", description: "等待 agent 时每段的长度。", display: (v) => `${v} 秒` },
+      permissionPollSeconds: { label: "权限检查间隔", description: "agent 等待批准时多久看一次。", display: (v) => `${v} 秒` },
+    },
+  },
+];
+
+const SECRET = /token|password|passwd|secret|webhook|api[_-]?key|authorization|cookie/i;
+
+/** The value with anything that looks like a secret, and people's accounts, replaced. */
+export function masked(value: unknown, key = ""): unknown {
+  if (key === "people" && value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value as object).map((name) => [name, "••••"]));
+  }
+  if (Array.isArray(value)) return value.map((v) => masked(v));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([k, v]) => [k, SECRET.test(k) && typeof v === "string" ? "••••" : masked(v, k)]));
+  }
+  return value;
+}
+
+function readRaw(file: string): Record<string, unknown> | null {
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, "utf8"));
+    return raw && typeof raw === "object" && !Array.isArray(raw) ? (raw as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+function plain(value: unknown): string {
+  if (value === null || value === undefined) return "未设置";
+  if (typeof value === "boolean") return onOff(value);
+  if (typeof value === "string" || typeof value === "number") return String(value);
+  return JSON.stringify(value);
+}
+
+/** The configuration that applies in `repo` (or on this machine, outside any project). */
+export function configView(configPath: string, repo: string | null): ConfigView {
+  const layers: Array<{ layer: Exclude<Layer, "default">; path: string; raw: Record<string, unknown> }> = [];
+  const machine = readRaw(configPath);
+  if (machine) layers.push({ layer: "machine", path: configPath, raw: machine });
+  if (machine && typeof machine.teamConfig === "string" && machine.teamConfig) {
+    const teamFile = path.resolve(path.dirname(configPath), machine.teamConfig);
+    const team = readRaw(teamFile);
+    if (team) layers.push({ layer: "team", path: teamFile, raw: team });
+  }
+  if (repo) {
+    const projectFile = path.join(repo, PROJECT_CONFIG_FILE);
+    const project = readRaw(projectFile);
+    if (project) layers.push({ layer: "project", path: projectFile, raw: project });
+  }
+
+  let config: PipelineConfig;
+  let error: string | null = null;
+  let ignored: string[] = [];
+  try {
+    const loaded = loadConfig(configPath, repo ?? undefined);
+    config = loaded.config;
+    ignored = loaded.ignored;
+  } catch (e) {
+    error = (e as Error).message;
+    config = { ...DEFAULT_CONFIG, ...Object.assign({}, ...layers.map((l) => l.raw)) } as PipelineConfig;
+  }
+
+  const allowed = (layer: Exclude<Layer, "default">, key: string) =>
+    layer === "machine" || (!(MACHINE_ONLY_KEYS as readonly string[]).includes(key) && !(layer === "project" && (NOT_IN_PROJECT_KEYS as readonly string[]).includes(key)));
+  const scopeOf = (key: string): ConfigItem["scope"] =>
+    (MACHINE_ONLY_KEYS as readonly string[]).includes(key) ? "machine" : (NOT_IN_PROJECT_KEYS as readonly string[]).includes(key) ? "machine_team" : "any";
+
+  const listed = new Set<string>();
+  const item = (key: string, entry: Entry): ConfigItem => {
+    listed.add(key);
+    const value = (config as unknown as Record<string, unknown>)[key];
+    let display: string;
+    try {
+      display = entry.display ? entry.display(value, config) : plain(value);
+    } catch {
+      display = plain(value);
+    }
+    return {
+      key,
+      label: entry.label,
+      description: entry.description,
+      display,
+      value: masked(value, key),
+      setBy: layers.filter((l) => key in l.raw && allowed(l.layer, key)).map((l) => l.layer),
+      scope: scopeOf(key),
+      changed: JSON.stringify(value) !== JSON.stringify((DEFAULT_CONFIG as unknown as Record<string, unknown>)[key]),
+    };
+  };
+  const groups: ConfigGroup[] = CATALOG.map((g) => ({ id: g.id, title: g.title, description: g.description, items: Object.entries(g.keys).map(([k, e]) => item(k, e)) }));
+  const rest = Object.keys(config).filter((k) => !listed.has(k));
+  if (rest.length > 0) {
+    groups.push({ id: "other", title: "其他", description: "上面没有归类的设置。", items: rest.map((k) => item(k, { label: k, description: "" })) });
+  }
+  return { sources: layers.map(({ layer, path: p }) => ({ layer, path: p })), ignored, error, repo, groups };
+}

package/engine/src/config.ts

@@ -147,6 +147,21 @@ export interface RelatedRepo {
   role?: string;
 }
 
+/**
+ * 1.12: after the push, a draft merge request made with the machine's own GitLab (or other)
+ * command, logged in beforehand. Placeholders: {branch} {target} {title} {description} {card}
+ * {cardUrl}. Never merged by req-kit.
+ */
+export interface MergeRequestSettings {
+  command: string;
+  args: string[];
+  /** Branch the merge request targets; default: the remote's default branch (origin/HEAD), else main. */
+  target?: string | null;
+  /** Arguments that check the command is logged in (req doctor), e.g. ["auth", "status"]. */
+  check?: string[] | null;
+  timeoutSeconds?: number;
+}
+
 export interface PipelineConfig {
   daemonUrl: string;
   /** Name of the environment variable holding the daemon password, if the daemon has one. */
@@ -192,6 +207,12 @@ export interface PipelineConfig {
   reviewPanel: ReviewPanelSettings;
   /** External notifiers (e.g. an internal IM). Machine or team config only. */
   notifiers: NotifierConfig[];
+  /**
+   * 1.12: how to reach people by name, for notifiers that send to a person: the requester's
+   * name as the card shows it → their accounts, e.g. { "张广祥": { "um": "ZHANGGX001" } }.
+   * Machine or team config only.
+   */
+  people: Record<string, Record<string, string>>;
   /** External systems kept in step with requirements, e.g. an ALM's CLI (1.9). Machine or team config only: they run commands. */
   integrations: IntegrationConfig[];
   /** Per integration name, values for its {field.*} placeholders; a project's file may set these (e.g. its project id). */
@@ -201,7 +222,7 @@ export interface PipelineConfig {
    * 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 };
+  push: { enabled: boolean; remote: string; branchPrefix: string; mergeRequest?: MergeRequestSettings | null };
   /**
    * 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
@@ -214,6 +235,11 @@ export interface PipelineConfig {
    * config only.
    */
   factory: { pollMinutes: number; titleTags: string[]; maxNewPerPoll: number };
+  /**
+   * 1.12: a requirement from a card that is small (quick profile) and has nothing to answer
+   * starts this many hours after its summary is on the card, unless the requester objects; 0: off.
+   */
+  autoConfirm: { hours: number };
   /** Automatic retries of a step after a transient error (rate limit, dropped connection). */
   retry: { attempts: number; backoffSeconds: number[] };
   /**
@@ -316,11 +342,13 @@ export const DEFAULT_CONFIG: PipelineConfig = {
   requiredVersion: null,
   reviewPanel: { enabled: false, steps: ["design_review", "code_review"], profiles: ["standard"], members: [] },
   notifiers: [],
+  people: {},
   integrations: [],
   integrationDefaults: {},
   push: { enabled: false, remote: "origin", branchPrefix: "req/" },
   cardSource: null,
   factory: { pollMinutes: 5, titleTags: ["[AI]", "【AI】"], maxNewPerPoll: 3 },
+  autoConfirm: { hours: 0 },
   retry: { attempts: 2, backoffSeconds: [60, 300] },
   paseoServices: "auto",
   serviceReadySeconds: 120,
@@ -388,6 +416,7 @@ function merge(base: PipelineConfig, raw: Record<string, unknown>): PipelineConf
   }
   merged.push = { ...base.push, ...(isRecord(raw.push) ? raw.push : {}) } as PipelineConfig["push"];
   merged.factory = { ...base.factory, ...(isRecord(raw.factory) ? raw.factory : {}) } as PipelineConfig["factory"];
+  merged.autoConfirm = { ...base.autoConfirm, ...(isRecord(raw.autoConfirm) ? raw.autoConfirm : {}) } as PipelineConfig["autoConfirm"];
   if (isRecord(raw.cardSource)) {
     const c = raw.cardSource;
     merged.cardSource = {
@@ -592,6 +621,17 @@ function validate(config: PipelineConfig): void {
   if (typeof push.enabled !== "boolean") throw new ConfigError("push.enabled 必须是 true 或 false");
   if (typeof push.remote !== "string" || !/^[\w.-]+$/.test(push.remote)) throw new ConfigError('push.remote 必须是远程仓库名，例如 "origin"');
   if (typeof push.branchPrefix !== "string" || !/^[A-Za-z0-9._-]+\/$/.test(push.branchPrefix)) throw new ConfigError('push.branchPrefix 必须是以 / 结尾的分支前缀，例如 "req/"');
+  const mr = push.mergeRequest;
+  if (mr !== undefined && mr !== null) {
+    if (!isRecord(mr) || typeof mr.command !== "string" || !mr.command.trim() || !Array.isArray(mr.args) || !mr.args.every((a) => typeof a === "string")) {
+      throw new ConfigError('push.mergeRequest 必须写成 { "command": "glab", "args": ["mr", "create", "--draft", …] }，参数中可以用 {branch} {target} {title} {description}');
+    }
+    if (!mr.args.some((a) => a.includes("{branch}"))) throw new ConfigError("push.mergeRequest.args 中要有 {branch}（推送的分支）");
+  }
+  if (!isRecord(config.people) || !Object.values(config.people).every((v) => isRecord(v) && Object.values(v).every((x) => typeof x === "string"))) {
+    throw new ConfigError('people 必须写成 { "<姓名>": { "<账号类型>": "<账号>" } }，例如 { "张广祥": { "um": "ZHANGGX001" } }');
+  }
+  if (typeof config.autoConfirm.hours !== "number" || config.autoConfirm.hours < 0) throw new ConfigError("autoConfirm.hours 必须是不小于 0 的小时数（0 表示关闭）");
   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 必须是正整数");
@@ -638,7 +678,7 @@ export interface LoadedConfig {
 }
 
 /** Keys a project file may not set: they run code or reach outside the repository. */
-const NOT_IN_PROJECT_KEYS = ["notifiers", "integrations", "push", "factory"] as const;
+export const NOT_IN_PROJECT_KEYS = ["notifiers", "integrations", "push", "factory", "people"] 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/doctor.ts

@@ -18,6 +18,7 @@ import { defaultConfigPath, findDependency, KIT_ROOT, kitVersion } from "./locat
 import { PROJECT_DIR } from "./prompts.js";
 import { describeAgentProfile, ProfileResolutionError, profilesFromDaemonConfig, resolveConfigProfiles, usesPaseoProfiles } from "./paseo-profiles.js";
 import { isAlive, STATE_VERSION } from "./state.js";
+import { resolveCommand } from "./integrations.js";
 
 const counts = { fail: 0, warn: 0 };
 const SYMBOL = { ok: "✓", warn: "⚠", fail: "✗" } as const;
@@ -141,6 +142,19 @@ function configuration(configPath: string, repo: string | null): PipelineConfig
         else report("warn", `关联仓库「${r.name}」不在这台机器上：${dir}`, "把它克隆到这个位置；或修改 relatedRepos 中的路径（相对项目目录，团队约定把相关仓库放在同一个上级目录最方便）");
       }
     }
+    const push = loaded.config.push;
+    if (push.enabled) {
+      report("ok", `推送分支：${push.remote}/${push.branchPrefix}<卡号>（只对从卡片开始的需求）`);
+      const mr = push.mergeRequest;
+      if (mr) {
+        if (mr.check && mr.check.length > 0) {
+          const { file, prefix } = resolveCommand(mr.command);
+          const r = spawnSync(file, [...prefix, ...mr.check], { encoding: "utf8", timeout: 30_000, windowsHide: true, cwd: repo ?? undefined });
+          if (r.status === 0) report("ok", `草稿合并请求：${mr.command} 已登录`);
+          else report("warn", `草稿合并请求：${mr.command} ${mr.check.join(" ")} 没有通过（${(r.error?.message ?? `${r.stderr ?? ""}${r.stdout ?? ""}`).trim().split("\n").slice(-1)[0] || `退出码 ${r.status}`}）`, `在这台机器上登录 ${mr.command}（例如 ${mr.command} auth login），否则分支照常推送，但不会建合并请求`);
+        } else report("ok", `草稿合并请求：推送后用 ${mr.command} 建（没有配置 check，无法检查是否已登录）`);
+      }
+    }
     const required = loaded.config.requiredVersion;
     if (required) {
       if (satisfies(kitVersion(), required)) report("ok", `版本要求 ${required}：当前 ${kitVersion()} 满足`);

package/engine/src/factory.ts

@@ -13,6 +13,7 @@
 
 import { spawn } from "node:child_process";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 import { parseArgs } from "node:util";
 import { cardRoutes, findCardEntry, hashText, parseJsonOutput } from "./card.js";
@@ -20,9 +21,10 @@ import { beginFromCard, type CardCmdOptions, cardIntegrations, checkCards, withR
 import { resumeCommand, statusCommand } from "./cli-args.js";
 import { loadConfig, type PipelineConfig } from "./config.js";
 import { watchdogPrompt } from "./messages.js";
+import { dispatchNotifiers } from "./notifiers.js";
 import { readIndex } from "./records.js";
 import { type IntegrationConfig, renderArgs, runCommand, type Runner } from "./integrations.js";
-import { defaultConfigPath, ENGINE_DIR, KIT_ROOT, kitHome } from "./locations.js";
+import { defaultConfigPath, ENGINE_DIR, KIT_ROOT, kitHome, kitVersion } from "./locations.js";
 import { isAlive, readState, statePath } from "./state.js";
 
 const USAGE = `用法：
@@ -54,6 +56,8 @@ export interface PollResult {
   relayed: string[];
   /** 1.12: interrupted pipelines whose chat was asked to continue them. */
   resumed: string[];
+  /** 1.12: what the self-check found wrong; no new cards are taken while it is not empty. */
+  problems: string[];
   errors: string[];
   notes: string[];
 }
@@ -148,7 +152,7 @@ export async function pollOnce(configPath: string, opts: CardCmdOptions = {}, no
   const env = opts.env ?? process.env;
   const dir = factoryDir(env);
   fs.mkdirSync(dir, { recursive: true });
-  const result: PollResult = { started: [], skipped: [], relayed: [], resumed: [], errors: [], notes: [] };
+  const result: PollResult = { started: [], skipped: [], relayed: [], resumed: [], problems: [], errors: [], notes: [] };
 
   // One look at a time on this machine.
   const lock = path.join(dir, "poll.lock");
@@ -163,13 +167,22 @@ export async function pollOnce(configPath: string, opts: CardCmdOptions = {}, no
     fs.writeFileSync(lock, String(process.pid));
   }
 
+  let config: PipelineConfig | null = null;
   try {
-    const config = loadConfig(configPath).config;
+    config = loadConfig(configPath).config;
+    // 1.12: Paseo, the agents and their quota must work before anything is taken on.
+    result.problems = opts.skipHealthCheck ? [] : await healthProblems(config);
+    if (result.problems.length > 0) {
+      result.notes.push("自检没有通过，这次不接新卡片、不转达回复");
+      throw new HealthStop();
+    }
     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;
+    let listAttempts = 0;
+    const listFailures: string[] = [];
     const integrations = cardIntegrations(config).filter((i) => i.list);
     if (integrations.length === 0) result.notes.push("没有配置可以列出卡片的外部系统（integrations 中的 list），只转达回复");
     for (const integration of integrations) {
@@ -180,9 +193,11 @@ export async function pollOnce(configPath: string, opts: CardCmdOptions = {}, no
       }
       for (const space of spaces) {
         let cards: ListedCard[];
+        listAttempts += 1;
         try {
           cards = await listCards(integration, space, tags[0], opts.run);
         } catch (error) {
+          listFailures.push(`${integration.name} 空间 ${space}：${(error as Error).message}`);
           result.errors.push(`${integration.name} 空间 ${space}：${(error as Error).message}`);
           continue;
         }
@@ -211,6 +226,9 @@ export async function pollOnce(configPath: string, opts: CardCmdOptions = {}, no
       }
     }
     writeJson(skippedFile, skipped);
+    if (listAttempts > 0 && listFailures.length === listAttempts) {
+      result.problems.push(`列不出卡片，需求管理系统的命令可能不可用：${listFailures[0].slice(0, 200)}`);
+    }
 
     try {
       await nudgeInterrupted(config, env, dir, result);
@@ -229,14 +247,105 @@ export async function pollOnce(configPath: string, opts: CardCmdOptions = {}, no
       result.errors.push(`转达回复：${(error as Error).message}`);
     }
   } catch (error) {
-    result.errors.push((error as Error).message);
+    if (!(error instanceof HealthStop)) result.errors.push((error as Error).message);
   } finally {
     fs.rmSync(lock, { force: true });
   }
+  if (config) await alertOnce(config, dir, result.problems, now);
   writeJson(path.join(dir, "status.json"), { lastPollAt: now.toISOString(), pid: process.pid, ...result });
   return result;
 }
 
+class HealthStop extends Error {}
+
+/** Runs `work`, giving up after `ms` (a daemon that is not running may never answer). */
+async function within<T>(ms: number, what: string, work: Promise<T>): Promise<T> {
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    return await Promise.race([work, new Promise<never>((_, reject) => (timer = setTimeout(() => reject(new Error(`${what}超过 ${ms / 1000} 秒没有响应`)), ms)))]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * 1.12: what keeps this machine from working on a new requirement: Paseo not reachable, an
+ * agent provider not logged in, the subscription used up. Empty when all is well.
+ */
+export async function healthProblems(config: PipelineConfig): Promise<string[]> {
+  const problems: string[] = [];
+  try {
+    await within(30_000, "连接 Paseo ", withRuntime(config, async (runtime, resolved) => {
+      const roles: Array<[string, string]> = [
+        ["builder", resolved.agents.builder.provider ?? ""],
+        ["reviewer", resolved.agents.reviewer.provider ?? ""],
+      ];
+      const status = await runtime.providerStatus();
+      for (const [role, full] of roles) {
+        const provider = full.split("/")[0];
+        if (!provider || !status) continue;
+        const found = status.find((s) => s.provider === provider);
+        if (!found || found.status !== "ready") problems.push(`${role} 用的 ${provider} ${found ? `不可用（${found.status}）` : "没有安装"}：在 Paseo 中登录它`);
+      }
+      // A used-up subscription matters when there is nothing else to fall back on.
+      const usable = [resolved.agents.builder, ...(resolved.agents.fallback ? [resolved.agents.fallback] : [])].map((p) => (p.provider ?? "").split("/")[0]).filter(Boolean);
+      const quotas = (await runtime.providerQuota([...new Set(usable)])) ?? [];
+      const exhausted = (provider: string) => quotas.some((q) => q.provider === provider && q.usedPct !== null && q.usedPct >= 100);
+      if (usable.length > 0 && usable.every(exhausted)) {
+        const q = quotas.find((x) => x.provider === usable[0] && x.usedPct !== null && x.usedPct >= 100)!;
+        problems.push(`${q.displayName} 的「${q.window}」额度已用完${q.resetsAt ? `，${new Date(q.resetsAt).toLocaleString("zh-CN", { hour12: false })} 恢复` : ""}`);
+      }
+    }));
+  } catch (error) {
+    problems.push(`连不上 Paseo（${(error as Error).message}）：确认这台机器上的 Paseo 正在运行`);
+  }
+  return problems;
+}
+
+/**
+ * Tells people once when the self-check starts failing (or what fails changes), and once when
+ * it passes again — not on every look. Through the configured notifiers (event "alert").
+ */
+async function alertOnce(config: PipelineConfig, dir: string, problems: string[], now: Date): Promise<void> {
+  const file = path.join(dir, "health.json");
+  const before = readJson<{ key: string; since: string | null }>(file, { key: "", since: null });
+  const key = problems.join("\n");
+  if (key === before.key) return;
+  writeJson(file, { key, since: problems.length > 0 ? now.toISOString() : null });
+  if (!key && !before.key) return;
+  const text = problems.length > 0
+    ? `接单器自检没有通过，暂停接新卡片：${problems.join("；")}`
+    : `接单器自检恢复正常，继续接卡片${before.since ? `（自 ${new Date(before.since).toLocaleString("zh-CN", { hour12: false })} 起暂停）` : ""}`;
+  appendLog(dir, text, now);
+  if (config.notifiers.length === 0) return;
+  await dispatchNotifiers(
+    config.notifiers,
+    {
+      schema: 1,
+      type: "alert",
+      at: now.toISOString(),
+      kitVersion: kitVersion(),
+      feature: { dir: "", name: "", title: "接单器" },
+      repo: "",
+      branch: null,
+      profile: "",
+      originAgentId: null,
+      text,
+      details: { source: "factory", machine: os.hostname(), problems, recovered: problems.length === 0 },
+      people: { audience: "team", requester: null, card: null, recipients: [] },
+    },
+    () => undefined,
+  );
+}
+
+function appendLog(dir: string, text: string, now: Date): void {
+  try {
+    fs.appendFileSync(path.join(dir, "factory.log"), `[${now.toLocaleString("zh-CN", { hour12: false })}] ${text}\n`);
+  } catch {
+    // The log is a convenience.
+  }
+}
+
 /**
  * 1.12: a pipeline on this machine still marked running whose process is gone (the machine
  * restarted, the process was killed): its chat gets the same message as the watchdog's, so
@@ -275,6 +384,7 @@ function describe(result: PollResult, now = new Date()): 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.resumed) lines.push(`[${stamp}] 续跑：${s}`);
+  for (const s of result.problems) 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}`);
@@ -373,6 +483,7 @@ function status(opts: CardCmdOptions): number {
   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 p of last.problems ?? []) out(`  自检：${p}（这期间不接新卡片）`);
     for (const e of last.errors) out(`  出错：${e}`);
     for (const n of last.notes) out(`  ${n}`);
   }