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

package/engine/src/steps.ts

@@ -0,0 +1,242 @@
+import type { AgentRole } from "./runtime.js";
+
+export type StepId =
+  | "design"
+  | "design_review"
+  | "design_revise"
+  | "implement"
+  | "code_review"
+  | "review_fix"
+  | "service_start"
+  | "verify"
+  | "defect_fix"
+  | "reverify"
+  | "report"
+  /** Handoff note for testing (提测说明), the last step of the develop phase. */
+  | "handoff"
+  /** One member of the optional review panel; runs before design_review / code_review consolidates. */
+  | "panel_review"
+  /** Independent review of a draft spec before the requester confirms it (run from the chat, not the pipeline). */
+  | "spec_review"
+  /** One of the parallel design proposals that the design step compares (optional). */
+  | "design_proposal";
+
+type FieldSpec =
+  | { kind: "boolean" }
+  | { kind: "enum"; values: readonly string[] }
+  | { kind: "string" }
+  | { kind: "string[]" };
+
+export interface ResultSpec {
+  required: Record<string, FieldSpec>;
+  optional?: Record<string, FieldSpec>;
+  /** Extra cross-field rule; returns an error message or null. */
+  check?: (value: Record<string, unknown>) => string | null;
+}
+
+export interface StepDef {
+  id: StepId;
+  /** Step number in the 11-step list the user defined. */
+  number: number;
+  title: string;
+  role: AgentRole;
+  promptFile: string;
+  result: ResultSpec;
+}
+
+const done: ResultSpec = { required: { status: { kind: "enum", values: ["done", "partial"] } } };
+
+/** Review steps that can run with a review panel. */
+export const PANEL_STEPS = ["design_review", "code_review"] as const;
+export type PanelStep = (typeof PANEL_STEPS)[number];
+
+export const STEPS: Record<StepId, StepDef> = {
+  spec_review: {
+    id: "spec_review",
+    number: 2,
+    title: "需求说明审阅",
+    role: "reviewer",
+    promptFile: "02-spec-review.md",
+    result: {
+      required: { verdict: { kind: "enum", values: ["ready", "issues"] } },
+      optional: { issues: { kind: "string[]" } },
+      check: (value) =>
+        value.verdict === "issues" && (!Array.isArray(value.issues) || value.issues.length === 0)
+          ? "verdict 为 issues 时，issues 必须是非空的字符串数组（每条一句话）"
+          : null,
+    },
+  },
+  design_proposal: {
+    id: "design_proposal",
+    number: 3,
+    title: "方案提案",
+    role: "builder",
+    promptFile: "03a-design-proposal.md",
+    result: done,
+  },
+  panel_review: {
+    id: "panel_review",
+    number: 0,
+    title: "评审小组成员",
+    role: "reviewer",
+    promptFile: "panel-member.md",
+    result: done,
+  },
+  design: {
+    id: "design",
+    number: 3,
+    title: "方案设计",
+    role: "builder",
+    promptFile: "03-design.md",
+    result: { required: { has_runnable_service: { kind: "boolean" } } },
+  },
+  design_review: {
+    id: "design_review",
+    number: 4,
+    title: "方案审核",
+    role: "reviewer",
+    promptFile: "04-design-review.md",
+    result: {
+      required: { verdict: { kind: "enum", values: ["approved", "changes_required", "blocked"] } },
+      optional: { questions: { kind: "string[]" } },
+      check: (value) =>
+        value.verdict === "blocked" && (!Array.isArray(value.questions) || value.questions.length === 0)
+          ? "verdict 为 blocked 时，questions 必须是非空的字符串数组"
+          : null,
+    },
+  },
+  design_revise: {
+    id: "design_revise",
+    number: 4,
+    title: "方案修订",
+    role: "builder",
+    promptFile: "04b-design-revise.md",
+    result: done,
+  },
+  implement: {
+    id: "implement",
+    number: 5,
+    title: "代码实现",
+    role: "builder",
+    promptFile: "05-implement.md",
+    result: done,
+  },
+  code_review: {
+    id: "code_review",
+    number: 6,
+    title: "代码评审",
+    role: "reviewer",
+    promptFile: "06-code-review.md",
+    result: { required: { verdict: { kind: "enum", values: ["pass", "changes_required"] } } },
+  },
+  review_fix: {
+    id: "review_fix",
+    number: 7,
+    title: "评审问题修复",
+    role: "builder",
+    promptFile: "07-review-fix.md",
+    result: done,
+  },
+  handoff: {
+    id: "handoff",
+    number: 7,
+    title: "提测说明",
+    role: "builder",
+    promptFile: "07b-handoff.md",
+    result: done,
+  },
+  service_start: {
+    id: "service_start",
+    number: 8,
+    title: "服务启动验证",
+    role: "builder",
+    promptFile: "08-service-start.md",
+    result: { required: { started: { kind: "boolean" } } },
+  },
+  verify: {
+    id: "verify",
+    number: 9,
+    title: "功能验证",
+    role: "reviewer",
+    promptFile: "09-verify.md",
+    result: { required: { result: { kind: "enum", values: ["pass", "defects_found", "blocked"] } } },
+  },
+  defect_fix: {
+    id: "defect_fix",
+    number: 10,
+    title: "缺陷修复",
+    role: "builder",
+    promptFile: "10-defect-fix.md",
+    result: done,
+  },
+  reverify: {
+    id: "reverify",
+    number: 10,
+    title: "复验",
+    role: "reviewer",
+    promptFile: "10b-reverify.md",
+    result: { required: { result: { kind: "enum", values: ["pass", "defects_remaining"] } } },
+  },
+  report: {
+    id: "report",
+    number: 11,
+    title: "完成报告",
+    role: "builder",
+    promptFile: "11-report.md",
+    result: {
+      required: {
+        outcome: { kind: "enum", values: ["completed", "completed_with_issues", "not_completed"] },
+        summary: { kind: "string" },
+      },
+    },
+  },
+};
+
+function checkField(name: string, spec: FieldSpec, value: unknown): string | null {
+  switch (spec.kind) {
+    case "boolean":
+      return typeof value === "boolean" ? null : `${name} 必须是 true 或 false`;
+    case "string":
+      return typeof value === "string" && value.trim() !== "" ? null : `${name} 必须是非空字符串`;
+    case "string[]":
+      return Array.isArray(value) && value.every((item) => typeof item === "string")
+        ? null
+        : `${name} 必须是字符串数组`;
+    case "enum":
+      return typeof value === "string" && spec.values.includes(value)
+        ? null
+        : `${name} 必须是 ${spec.values.map((v) => `"${v}"`).join(" / ")} 之一`;
+  }
+}
+
+export type ValidationResult =
+  | { ok: true; value: Record<string, unknown> }
+  | { ok: false; error: string };
+
+export function validateResult(spec: ResultSpec, raw: unknown): ValidationResult {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    return { ok: false, error: "内容必须是一个 JSON 对象" };
+  }
+  const value = raw as Record<string, unknown>;
+  for (const [name, field] of Object.entries(spec.required)) {
+    if (!(name in value)) return { ok: false, error: `缺少字段 ${name}` };
+    const error = checkField(name, field, value[name]);
+    if (error) return { ok: false, error };
+  }
+  for (const [name, field] of Object.entries(spec.optional ?? {})) {
+    if (name in value && value[name] !== undefined) {
+      const error = checkField(name, field, value[name]);
+      if (error) return { ok: false, error };
+    }
+  }
+  const crossError = spec.check?.(value) ?? null;
+  if (crossError) return { ok: false, error: crossError };
+  return { ok: true, value };
+}
+
+/** Steps of the verify phase; they may use phases.verify.agents. */
+export const VERIFY_PHASE_STEPS: readonly StepId[] = ["service_start", "verify", "defect_fix", "reverify"];
+
+export function stepKey(id: StepId, round: number | null): string {
+  return round === null ? id : `${id}-r${round}`;
+}

package/engine/src/usage.ts

@@ -0,0 +1,67 @@
+// Time and token usage per step, as reported by the agents, and plain-language summaries.
+
+export interface AgentUsage {
+  inputTokens?: number;
+  cachedInputTokens?: number;
+  outputTokens?: number;
+  totalCostUsd?: number;
+}
+
+interface UsageRecord {
+  attempt: number;
+  startedAt: string;
+  endedAt: string | null;
+  usage?: AgentUsage | null;
+}
+
+export interface UsageTotals {
+  steps: number;
+  /** Sum of step durations (steps of a review panel overlap, so this can exceed wall time). */
+  agentMinutes: number;
+  inputTokens: number | null;
+  outputTokens: number | null;
+  costUsd: number | null;
+}
+
+function add(total: number | null, value: number | undefined): number | null {
+  return typeof value === "number" ? (total ?? 0) + value : total;
+}
+
+export function totals(records: UsageRecord[], now = new Date()): UsageTotals {
+  let agentMinutes = 0;
+  let inputTokens: number | null = null;
+  let outputTokens: number | null = null;
+  let costUsd: number | null = null;
+  for (const r of records) {
+    const end = r.endedAt ? new Date(r.endedAt) : now;
+    agentMinutes += Math.max(0, (end.getTime() - new Date(r.startedAt).getTime()) / 60_000);
+    inputTokens = add(inputTokens, r.usage?.inputTokens);
+    outputTokens = add(outputTokens, r.usage?.outputTokens);
+    costUsd = add(costUsd, r.usage?.totalCostUsd);
+  }
+  return { steps: records.length, agentMinutes, inputTokens, outputTokens, costUsd };
+}
+
+function tokens(n: number): string {
+  return n >= 10_000 ? `${(n / 10_000).toFixed(1).replace(/\.0$/, "")} 万` : String(n);
+}
+
+function minutes(m: number): string {
+  if (m < 1) return "不到 1 分钟";
+  if (m < 60) return `${Math.round(m)} 分钟`;
+  const h = Math.floor(m / 60);
+  const rest = Math.round(m % 60);
+  return rest === 0 ? `${h} 小时` : `${h} 小时 ${rest} 分`;
+}
+
+/** e.g. "6 个步骤，agent 合计用时 2 小时 5 分；输入 120 万 tokens，输出 8.3 万 tokens，约 $4.20" */
+export function describeTotals(t: UsageTotals): string {
+  const parts = [`${t.steps} 个步骤，agent 合计用时 ${minutes(t.agentMinutes)}`];
+  const usage: string[] = [];
+  if (t.inputTokens !== null) usage.push(`输入 ${tokens(t.inputTokens)} tokens`);
+  if (t.outputTokens !== null) usage.push(`输出 ${tokens(t.outputTokens)} tokens`);
+  if (t.costUsd !== null) usage.push(`约 $${t.costUsd.toFixed(2)}`);
+  if (usage.length > 0) parts.push(usage.join("，"));
+  else parts.push("agent 没有报告 token 用量");
+  return parts.join("；");
+}

package/engine/src/worktree.ts

@@ -0,0 +1,72 @@
+// --worktree: develop a requirement in a Paseo worktree workspace created for it.
+// The chat stays where it is (its working directory never changes); the spec moves
+// to the new worktree, is committed there on its own branch, and the step agents are
+// placed in that workspace while remaining subagents of the chat. See ADR 0018.
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import type { AgentRuntime } from "./runtime.js";
+
+function git(cwd: string, ...args: string[]): string {
+  return execFileSync("git", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+}
+
+export interface OwnWorktree {
+  repo: string;
+  workspaceId: string;
+  branch: string;
+  /** Whether the uncommitted copy in the chat's checkout was removed after moving. */
+  removedSource: boolean;
+}
+
+export async function moveToOwnWorktree(input: {
+  runtime: Pick<AgentRuntime, "createWorktree">;
+  sourceRepo: string;
+  featureDir: string;
+  originAgentId: string | null;
+  title: string;
+}): Promise<OwnWorktree> {
+  const { sourceRepo, featureDir } = input;
+  const branch = `feature/${path.basename(featureDir)}`;
+  try {
+    git(sourceRepo, "show-ref", "--verify", "--quiet", `refs/heads/${branch}`);
+    throw new Error(`分支 ${branch} 已经存在。这个需求可能已经有自己的工作区了：用 --list 查看，或在那个工作区的对话中继续。`);
+  } catch (error) {
+    if ((error as Error).message.startsWith("分支")) throw error;
+    // show-ref failed: the branch does not exist yet, as expected.
+  }
+  const head = git(sourceRepo, "rev-parse", "--abbrev-ref", "HEAD");
+  const baseRef = head === "HEAD" ? git(sourceRepo, "rev-parse", "HEAD") : head;
+
+  const created = await input.runtime.createWorktree({
+    sourceRepo,
+    baseRef,
+    branchName: branch,
+    title: input.title,
+    callerAgentId: input.originAgentId,
+  });
+  const repo = fs.realpathSync(created.directory);
+
+  // The spec and interview notes were written in the chat's checkout; move them over.
+  const from = path.join(sourceRepo, featureDir);
+  const to = path.join(repo, featureDir);
+  fs.mkdirSync(to, { recursive: true });
+  fs.cpSync(from, to, { recursive: true, filter: (src) => path.basename(src) !== ".pipeline" });
+  git(repo, "add", "--", featureDir);
+  const staged = git(repo, "diff", "--cached", "--name-only", "--", featureDir);
+  if (staged) {
+    try {
+      git(repo, "commit", "-q", "-m", `docs(req): ${input.title} 需求说明`, "--", featureDir);
+    } catch (error) {
+      const stderr = (error as { stderr?: Buffer | string }).stderr?.toString().trim();
+      throw new Error(`在新工作区 ${repo} 中提交需求说明失败：${stderr || (error as Error).message}`);
+    }
+  }
+
+  // Leave nothing behind in the chat's checkout unless it was already committed there.
+  const tracked = git(sourceRepo, "ls-files", "--", featureDir);
+  const removedSource = tracked === "";
+  if (removedSource) fs.rmSync(from, { recursive: true, force: true });
+  return { repo, workspaceId: created.workspaceId, branch, removedSource };
+}