paseo-req-kit 0.0.0-stage → 1.7.0-beta.3

package/engine/src/smoke-test.ts

@@ -0,0 +1,202 @@
+// Checks the parts of the pipeline that depend on your real Paseo setup.
+//
+//   npm run smoke -- check                        daemon, providers, models, modes; one tiny agent per role
+//   npm run smoke -- notify --origin-agent <id>   message + subagent into an existing chat
+//   npm run smoke -- detach-start                 start a background heartbeat (run from a Paseo chat)
+//   npm run smoke -- detach-check                 is that heartbeat still alive?
+//
+// See docs/guide/安装与升级.md, "冒烟测试", for when to run each one.
+
+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 { type AgentProfile, loadConfig, type PipelineConfig } from "./config.js";
+import { checkProfile as checkProfileWith, type Client, connect, type Report, resolveWithDaemon } from "./daemon-check.js";
+import { defaultConfigPath } from "./locations.js";
+
+const HEARTBEAT = path.join(os.tmpdir(), "requirement-pipeline-heartbeat.json");
+
+function line(ok: boolean, text: string): void {
+  console.log(`${ok ? "✓" : "✗"} ${text}`);
+}
+
+const report: Report = (level, text, fix) => {
+  line(level !== "fail", text);
+  if (fix) console.log(`  ${fix}`);
+};
+
+async function tinyAgent(client: Client, role: string, profile: AgentProfile): Promise<boolean> {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), `requirement-pipeline-smoke-${role}-`));
+  const agent = await client.agents.create({
+    config: {
+      provider: profile.provider ?? "",
+      ...(profile.modeId ? { modeId: profile.modeId } : {}),
+      ...(profile.thinkingOptionId ? { thinkingOptionId: profile.thinkingOptionId } : {}),
+      ...(profile.featureValues ? { featureValues: profile.featureValues } : {}),
+    },
+    cwd: dir,
+    title: `[冒烟测试] ${role}`,
+    labels: { "requirement-pipeline": "smoke-test" },
+    prompt: `在当前目录创建文件 smoke.txt，内容只有一行：ok-${role}。然后用 node 执行 \`node -e "require('fs').writeFileSync('shell.txt','ran')"\`。完成后直接结束，不要做其他事。`,
+  });
+  console.log(`  已创建 agent ${agent.id}，等待它完成（最多 5 分钟）……`);
+  try {
+    const result = await agent.waitForFinish(5 * 60_000);
+    if (result.status === "permission") {
+      line(false, `${role}：agent 停下来等待权限批准。请把 agents.${role}.modeId 改成免确认的模式。`);
+      return false;
+    }
+    if (result.status !== "idle") {
+      line(false, `${role}：agent 结束状态为 ${result.status}：${result.error ?? ""}`);
+      return false;
+    }
+    const wrote = fs.existsSync(path.join(dir, "smoke.txt"));
+    const ran = fs.existsSync(path.join(dir, "shell.txt"));
+    line(wrote && ran, `${role}：agent 能写文件${wrote ? "" : "（失败）"}、能执行命令${ran ? "" : "（失败）"}`);
+    return wrote && ran;
+  } finally {
+    await agent.archive().catch(() => undefined);
+  }
+}
+
+async function check(config: PipelineConfig): Promise<number> {
+  let client: Client;
+  try {
+    client = await connect(config);
+    line(true, `已连接 daemon：${config.daemonUrl}`);
+  } catch (error) {
+    line(false, `无法连接 daemon ${config.daemonUrl}：${(error as Error).message}`);
+    return 1;
+  }
+  try {
+    const snapshot = await client.providers.waitForReady({ timeoutMs: 60_000 });
+    console.log("  daemon 上可用的 provider：");
+    for (const entry of snapshot.entries) {
+      console.log(`    - ${entry.provider}（${entry.status}）`);
+    }
+    try {
+      config = await resolveWithDaemon(client, config);
+    } catch (error) {
+      line(false, (error as Error).message);
+      return 1;
+    }
+    let ok = true;
+    for (const role of ["builder", "reviewer"] as const) {
+      ok = (await checkProfileWith(client, role, config.agents[role], report)) && ok;
+    }
+    if (!ok) {
+      console.log("\n请先修正 ~/.req-kit/config.json 中的 provider/model 和 modeId，再重新运行。");
+      return 1;
+    }
+    for (const role of ["builder", "reviewer"] as const) {
+      ok = (await tinyAgent(client, role, config.agents[role])) && ok;
+    }
+    console.log(ok ? "\n全部通过。" : "\n有检查没有通过，见上面的 ✗。");
+    return ok ? 0 : 1;
+  } finally {
+    await client.close();
+  }
+}
+
+async function notify(config: PipelineConfig, origin: string): Promise<number> {
+  const client = await connect(config);
+  try {
+    await client.agents.ref(origin).send(
+      "【需求开发流水线通知】这是一条冒烟测试消息，不是用户发的。请回复用户：\"流水线的通知通道工作正常。\"",
+      { activeTurnBehavior: "steer" },
+    );
+    line(true, `已向 agent ${origin} 发送测试通知。请到该对话中确认 agent 转告了"通知通道工作正常"。`);
+
+    config = await resolveWithDaemon(client, config);
+    const child = await client.agents.create({
+      config: {
+        provider: config.agents.builder.provider ?? "",
+        ...(config.agents.builder.modeId ? { modeId: config.agents.builder.modeId } : {}),
+      },
+      cwd: process.cwd(),
+      parent: origin,
+      title: "[冒烟测试] 子 agent",
+      labels: { "requirement-pipeline": "smoke-test" },
+      prompt: "只回复\"ok\"，然后结束。不要读写任何文件。",
+    });
+    const result = await child.waitForFinish(3 * 60_000);
+    line(result.status === "idle", `已在该对话下创建子 agent ${child.id}（结束状态 ${result.status}）。请确认它出现在对话的子 agent 列表中。`);
+    await child.archive().catch(() => undefined);
+    return result.status === "idle" ? 0 : 1;
+  } catch (error) {
+    line(false, (error as Error).message);
+    return 1;
+  } finally {
+    await client.close();
+  }
+}
+
+function detachStart(): number {
+  const script = `
+    const fs = require("fs");
+    const end = Date.now() + 10 * 60_000;
+    const beat = () => fs.writeFileSync(${JSON.stringify(HEARTBEAT)}, JSON.stringify({ pid: process.pid, at: Date.now(), startedAt }));
+    const startedAt = Date.now();
+    beat();
+    const timer = setInterval(() => { if (Date.now() > end) { clearInterval(timer); return; } beat(); }, 2000);
+  `;
+  // Same detach mechanism as launch.ts.
+  const child = spawn(process.execPath, ["-e", script], { detached: true, windowsHide: true, stdio: "ignore" });
+  child.unref();
+  console.log(`已启动后台心跳进程 ${child.pid}（持续 10 分钟），心跳文件：${HEARTBEAT}`);
+  console.log("请结束这一轮对话，等待至少 1 分钟后，再让 agent 运行 detach-check。");
+  return 0;
+}
+
+function detachCheck(): number {
+  if (!fs.existsSync(HEARTBEAT)) {
+    line(false, "找不到心跳文件，请先运行 detach-start");
+    return 1;
+  }
+  const beat = JSON.parse(fs.readFileSync(HEARTBEAT, "utf8")) as { pid: number; at: number; startedAt: number };
+  const age = Math.round((Date.now() - beat.at) / 1000);
+  const ranFor = Math.round((beat.at - beat.startedAt) / 1000);
+  const alive = age < 10;
+  line(
+    alive,
+    alive
+      ? `后台进程 ${beat.pid} 仍在运行（已运行 ${ranFor} 秒）。聊天 agent 启动的后台流水线可以在它的回合结束后继续运行。`
+      : `后台进程 ${beat.pid} 在启动后约 ${ranFor} 秒停止（最后一次心跳在 ${age} 秒前）。` +
+          "聊天 agent 的回合结束时，它启动的后台进程被终止了；需要改用插件方式启动流水线。",
+  );
+  return alive ? 0 : 1;
+}
+
+async function main(): Promise<number> {
+  const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    options: { "origin-agent": { type: "string" }, config: { type: "string" } },
+    allowPositionals: true,
+  });
+  const command = positionals[0];
+  if (command === "detach-start") return detachStart();
+  if (command === "detach-check") return detachCheck();
+
+  const config = loadConfig(values.config ? path.resolve(values.config) : defaultConfigPath()).config;
+  if (command === "check") return check(config);
+  if (command === "notify") {
+    const origin = values["origin-agent"] ?? process.env.PASEO_AGENT_ID;
+    if (!origin) {
+      console.error("需要 --origin-agent <agent ID>，或在 Paseo 的聊天中运行（自动读取 PASEO_AGENT_ID）");
+      return 2;
+    }
+    return notify(config, origin);
+  }
+  console.error("用法：npm run smoke -- check | notify --origin-agent <id> | detach-start | detach-check");
+  return 2;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error: Error) => {
+    console.error(error.message);
+    process.exit(1);
+  },
+);

package/engine/src/spec-review.ts

@@ -0,0 +1,100 @@
+// Independent review of a draft spec, started from the chat before the requester
+// confirms it (launch.ts --spec-review). Runs one "spec_review" agent under the chat,
+// waits for it in the background, then posts the findings back into the chat.
+
+import fs from "node:fs";
+import path from "node:path";
+import { parseLaunchArgs } from "./cli-args.js";
+import { loadConfig } from "./config.js";
+import { defaultConfigPath, KIT_ROOT, localPromptsDir, PRINCIPLES_INDEX, PROMPTS_DIR } from "./locations.js";
+import { specReviewFailedMessage, specReviewMessage } from "./messages.js";
+import { resolveConfigProfiles, usesPaseoProfiles } from "./paseo-profiles.js";
+import { runSingleStep } from "./pipeline.js";
+import { normalizeFeatureDir, specProfile } from "./preflight.js";
+import { loadRuntimeFactory } from "./runtime-loader.js";
+import { ensurePipelineDir, hashFile, type PipelineState, pipelineDir, STATE_VERSION } from "./state.js";
+
+function log(message: string): void {
+  console.log(`[${new Date().toISOString()}] ${message}`);
+}
+
+async function main(): Promise<number> {
+  const args = parseLaunchArgs(process.argv.slice(2));
+  const repo = fs.realpathSync(args.repo);
+  const featureDir = normalizeFeatureDir(repo, args.featureDir);
+  const specPath = path.join(repo, featureDir, "spec.md");
+  let config = loadConfig(args.configPath ?? defaultConfigPath(), repo).config;
+  ensurePipelineDir(repo, featureDir);
+  const runtime = await (await loadRuntimeFactory())({ config, log });
+  const origin = args.originAgentId;
+  const notify = async (text: string) => {
+    log(`通知：\n${text}`);
+    if (origin) await runtime.notifyAgent(origin, text).catch((error: Error) => log(`通知发送失败：${error.message}`));
+  };
+  try {
+    if (origin) await runtime.verifyOrigin(origin, repo);
+    if (usesPaseoProfiles(config)) config = resolveConfigProfiles(config, await runtime.listPaseoProfiles());
+    const now = new Date().toISOString();
+    // A scratch state: the review is not part of a pipeline run and must not touch state.json.
+    const state: PipelineState = {
+      version: STATE_VERSION,
+      repo,
+      featureDir,
+      status: "running",
+      attempt: 1,
+      specHash: hashFile(specPath),
+      originAgentId: origin,
+      pid: process.pid,
+      startedAt: now,
+      updatedAt: now,
+      results: {},
+      history: [],
+      stopReason: null,
+      outcome: null,
+      profile: specProfile(fs.readFileSync(specPath, "utf8")) ?? config.defaultProfile,
+      branch: null,
+      milestones: [],
+      incremental: null,
+    };
+    const result = await runSingleStep(
+      {
+        repo,
+        featureDir,
+        config,
+        runtime,
+        state,
+        statePath: path.join(pipelineDir(repo, featureDir), "spec-review-state.json"),
+        prompts: { promptsDir: PROMPTS_DIR, localPromptsDir: localPromptsDir(), principlesFile: PRINCIPLES_INDEX },
+        logPath: path.join(pipelineDir(repo, featureDir), "spec-review.log"),
+        resumeCommand: "",
+        log,
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+      },
+      "spec_review",
+      { contextLines: [`需求说明的写法清单：${path.join(KIT_ROOT, "skills", "spec-writing", "SKILL.md")}`] },
+    );
+    await notify(
+      specReviewMessage({
+        featureDir,
+        verdict: String(result.verdict),
+        issues: (result.issues as string[] | undefined) ?? [],
+        reviewPath: `${featureDir}/spec-review.md`,
+      }),
+    );
+    return 0;
+  } catch (error) {
+    log(`审阅没有完成：${(error as Error).message}`);
+    await notify(specReviewFailedMessage({ featureDir, reason: (error as Error).message }));
+    return 1;
+  } finally {
+    await runtime.close().catch(() => undefined);
+  }
+}
+
+main().then(
+  (code) => process.exit(code),
+  (error: Error) => {
+    console.error(`[${new Date().toISOString()}] 需求说明审阅无法启动：${error.message}`);
+    process.exit(2);
+  },
+);

package/engine/src/state.ts

@@ -0,0 +1,278 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { DefectHandling, PhaseMode, ProfileName, VerifyEnvironment } from "./config.js";
+import type { AgentUsage } from "./usage.js";
+import type { StepId } from "./steps.js";
+
+/**
+ * "phase_done": the develop phase is done and the run stopped at the gate, waiting for
+ * someone to start the verify phase (phases.mode "gated"). Engines before 1.7 treat an
+ * unknown status as an interrupted run, which continues into verification: acceptable.
+ */
+export type PipelineStatus = "running" | "waiting_for_business" | "failed" | "completed" | "phase_done";
+
+/** Phase names are strings so later phases need no format change. */
+export type PhaseName = "develop" | "verify";
+
+/** Execution mode and verify-phase options a run settled on (absent before 1.7: continuous). */
+export interface RunPhases {
+  mode: PhaseMode;
+  environment: VerifyEnvironment;
+  defects: DefectHandling;
+}
+
+export interface StepRecord {
+  key: string;
+  stepId: StepId;
+  round: number | null;
+  attempt: number;
+  agentId: string;
+  startedAt: string;
+  endedAt: string | null;
+  outcome: "running" | "completed" | "failed";
+  followUps: number;
+  result: Record<string, unknown> | null;
+  error: string | null;
+  /** Latest usage the agent reported for this step; absent in older state files. */
+  usage?: AgentUsage | null;
+  /** Phase the step ran in; absent before 1.7 (develop or verify by step). */
+  phase?: PhaseName;
+}
+
+export interface PipelineState {
+  /** Format version, see STATE_VERSION. */
+  version: number;
+  repo: string;
+  featureDir: string;
+  status: PipelineStatus;
+  /** Incremented every time the pipeline starts over from the design step. */
+  attempt: number;
+  specHash: string;
+  originAgentId: string | null;
+  pid: number;
+  startedAt: string;
+  updatedAt: string;
+  /** Completed step results by step key. A resumed run reuses these instead of re-running the step. */
+  results: Record<string, Record<string, unknown>>;
+  history: StepRecord[];
+  stopReason: string | null;
+  outcome: string | null;
+  /** "quick" or "standard"; decides loop rounds and optional steps. */
+  profile: ProfileName;
+  /** Git branch the run commits to, fixed at launch. Null outside a git repository. */
+  branch: string | null;
+  /** Progress notes already sent, so a resumed run does not repeat them. */
+  milestones: string[];
+  /**
+   * Set when this attempt restarted from design because the requirement changed (or a
+   * business decision was answered): the steps build on the existing design and code
+   * instead of starting over. Absent in older state files.
+   */
+  incremental?: IncrementalInfo | null;
+  /**
+   * Set when the requirement is developed in a worktree created for it (--worktree):
+   * the Paseo workspace and the checkout the chat works in. `repo` is the worktree.
+   */
+  worktree?: { workspaceId: string; sourceRepo: string } | null;
+  /** Paseo schedules this run created (reminders, automatic continuation, watchdog); cancelled by the next run. */
+  schedules?: Array<{ id: string; kind: "reminder" | "auto-resume" | "watchdog" | "verify-start"; at: string | null }>;
+  /** Automatic continuations used in this attempt. */
+  autoResumes?: { attempt: number; count: number } | null;
+  /** Set while waiting for a free slot (maxConcurrentPipelines). */
+  queuedSince?: string | null;
+  /** Execution mode of this run; absent in older state files (continuous). */
+  phases?: RunPhases | null;
+  /** Current phase; absent in older state files. */
+  phase?: PhaseName;
+  /** --verify-at: when the verify phase should start once development is done (ISO time). */
+  verifyAt?: string | null;
+  /** How many times the verify phase handed defects back to development (defects "handback"). */
+  handbacks?: number;
+}
+
+export interface IncrementalInfo {
+  /** Attempt whose work this one continues. */
+  fromAttempt: number;
+  reason: string;
+  /** Commit at the start of this attempt; reviewers look at changes since here. Null outside git. */
+  baseCommit: string | null;
+  /** Whether the previous attempt got as far as writing code. */
+  hadImplementation: boolean;
+}
+
+export function pipelineDir(repo: string, featureDir: string): string {
+  return path.join(repo, featureDir, ".pipeline");
+}
+
+export function statePath(repo: string, featureDir: string): string {
+  return path.join(pipelineDir(repo, featureDir), "state.json");
+}
+
+export function ensurePipelineDir(repo: string, featureDir: string): string {
+  const dir = pipelineDir(repo, featureDir);
+  fs.mkdirSync(path.join(dir, "results"), { recursive: true });
+  const ignore = path.join(dir, ".gitignore");
+  // Runtime files only; never committed by the step agents.
+  if (!fs.existsSync(ignore)) fs.writeFileSync(ignore, "*\n");
+  return dir;
+}
+
+/**
+ * Format version of state.json written by this engine. Bump it when the shape changes
+ * and add a migration from the previous version to STATE_MIGRATIONS.
+ */
+export const STATE_VERSION = 1;
+
+/** Upgrades a state object from version `n` to `n + 1`. */
+export type StateMigration = (state: Record<string, unknown>) => Record<string, unknown>;
+
+/** Keyed by the version a migration upgrades from. */
+export const STATE_MIGRATIONS: Record<number, StateMigration> = {};
+
+export class StateVersionError extends Error {
+  constructor(file: string, found: number, supported: number) {
+    super(
+      `${file} 是由更新版本的 req-kit 写入的（格式第 ${found} 版，当前版本只支持到第 ${supported} 版）。` +
+        "请升级 req-kit 后再操作；如果是回滚到旧版本造成的，可以把同目录下的 state.json.bak-v<旧版本号> 恢复为 state.json，" +
+        "或者删除 state.json 后用 --restart 从头开始。",
+    );
+    this.name = "StateVersionError";
+  }
+}
+
+/**
+ * Brings a parsed state object up to `target`, one version at a time.
+ * Files written before the version field existed count as version 1.
+ */
+export function migrateState(
+  raw: Record<string, unknown>,
+  file: string,
+  migrations: Record<number, StateMigration> = STATE_MIGRATIONS,
+  target: number = STATE_VERSION,
+): { state: Record<string, unknown>; from: number } {
+  const from = typeof raw.version === "number" ? raw.version : 1;
+  if (from > target) throw new StateVersionError(file, from, target);
+  let state = raw;
+  for (let version = from; version < target; version += 1) {
+    const step = migrations[version];
+    if (!step) throw new Error(`缺少 state.json 从第 ${version} 版到第 ${version + 1} 版的迁移`);
+    state = { ...step(state), version: version + 1 };
+  }
+  return { state, from };
+}
+
+/**
+ * Reads state.json, migrating an older format in place. The file as it was is kept
+ * next to it as state.json.bak-v<old version>, so a rollback can restore it.
+ */
+export function readState(
+  file: string,
+  migrations: Record<number, StateMigration> = STATE_MIGRATIONS,
+  target: number = STATE_VERSION,
+): PipelineState | null {
+  if (!fs.existsSync(file)) return null;
+  const text = fs.readFileSync(file, "utf8");
+  const raw = JSON.parse(text) as Record<string, unknown>;
+  const { state, from } = migrateState(raw, file, migrations, target);
+  if (from < target) {
+    const backup = `${file}.bak-v${from}`;
+    if (!fs.existsSync(backup)) fs.writeFileSync(backup, text);
+    const tmp = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+    fs.renameSync(tmp, file);
+  }
+  return state as unknown as PipelineState;
+}
+
+export function writeState(file: string, state: PipelineState): void {
+  state.updatedAt = new Date().toISOString();
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+}
+
+export function hashFile(file: string): string {
+  return crypto.createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+}
+
+// ---------------------------------------------------------------------------
+// One pipeline per repository checkout: the steps switch branches and commit,
+// so two pipelines in the same directory would corrupt each other's work.
+// ---------------------------------------------------------------------------
+
+export interface LockInfo {
+  pid: number;
+  featureDir: string;
+  startedAt: string;
+}
+
+export function lockPath(repo: string): string {
+  const id = crypto.createHash("sha1").update(fs.realpathSync(repo)).digest("hex").slice(0, 12);
+  return path.join(os.tmpdir(), `requirement-pipeline-${id}.lock`);
+}
+
+export function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+/** Returns the live holder of the repository lock, or null. Removes a stale lock. */
+export function currentLockHolder(repo: string): LockInfo | null {
+  const file = lockPath(repo);
+  if (!fs.existsSync(file)) return null;
+  try {
+    const info = JSON.parse(fs.readFileSync(file, "utf8")) as LockInfo;
+    if (isAlive(info.pid)) return info;
+  } catch {
+    // Unreadable lock: treat as stale.
+  }
+  fs.rmSync(file, { force: true });
+  return null;
+}
+
+export function acquireLock(repo: string, featureDir: string): () => void {
+  const file = lockPath(repo);
+  const holder = currentLockHolder(repo);
+  if (holder && holder.pid !== process.pid) {
+    throw new LockHeldError(holder);
+  }
+  const info: LockInfo = { pid: process.pid, featureDir, startedAt: new Date().toISOString() };
+  try {
+    fs.writeFileSync(file, JSON.stringify(info), { flag: holder ? "w" : "wx" });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+      const other = currentLockHolder(repo);
+      if (other) throw new LockHeldError(other);
+      fs.writeFileSync(file, JSON.stringify(info), { flag: "wx" });
+    } else {
+      throw error;
+    }
+  }
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    try {
+      const now = JSON.parse(fs.readFileSync(file, "utf8")) as LockInfo;
+      if (now.pid === process.pid) fs.rmSync(file, { force: true });
+    } catch {
+      // Already gone.
+    }
+  };
+}
+
+export class LockHeldError extends Error {
+  constructor(public readonly holder: LockInfo) {
+    super(
+      `这个仓库目录已有一条流水线在运行（进程 ${holder.pid}，功能目录 ${holder.featureDir}，开始于 ${holder.startedAt}）。` +
+        "同一个目录一次只能运行一条，请等它结束。",
+    );
+    this.name = "LockHeldError";
+  }
+}