aitable-workflow-cli 0.1.28 → 0.1.29-beta.1790736949347

package/templates/ai-native-sdlc/lib/recipe-helpers.ts

@@ -0,0 +1,595 @@
+import type {
+  CodingRunResult,
+  MrComment,
+  RecipeContext,
+  RecipeResult,
+} from "aitable-workflow-core";
+import { repositoryConfig, type RepositoryConfig } from "./recipe-config.js";
+
+
+export function text(value: unknown): string {
+  return typeof value === "string" ? value.trim() : "";
+}
+
+/**
+ * singleSelect 单元格读回是 `{id, name}` 对象而非字符串，
+ * 直接与字面量比较会永远不相等（受理门禁因此永久阻塞）。比较前必须取 name。
+ */
+export function selectName(value: unknown): string {
+  if (typeof value === "string") return value.trim();
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const name = (value as Record<string, unknown>).name;
+    if (typeof name === "string") return name.trim();
+  }
+  return "";
+}
+
+export function recordValue(
+  row: Record<string, unknown>,
+  name: string,
+): string {
+  return text(row[name]);
+}
+
+/**
+ * 测试需求仍必须走真实 Agent、Git 与 CR；只收窄 Agent 的调研范围，避免一次端到端验证遍历业务代码库。
+ * 标记写在标题而非运行字段，保证所有阶段与恢复会话都能从同一持久化记录复现这个边界。
+ */
+export function isTestDemand(row: Record<string, unknown>): boolean {
+  const title = recordValue(row, "标题") || recordValue(row, "需求");
+  return title.startsWith("【测试】");
+}
+
+export function testDemandInstruction(row: Record<string, unknown>): string {
+  if (!isTestDemand(row)) return "";
+  return "## 测试需求模式\n这是测试需求。立即遵循工作目录 AGENTS.md 的测试模式，以最短步骤完成本阶段，不得调研业务代码库。";
+}
+
+export function repositoryUrl(repository: RepositoryConfig): string {
+  return repository.url;
+}
+
+export function requireRepository(
+  ctx: RecipeContext,
+  key: string,
+): RepositoryConfig | undefined {
+  const parsed = repositoryConfig.safeParse(ctx.config[key]);
+  return parsed.success ? parsed.data : undefined;
+}
+
+export function requireRepositories(
+  ctx: RecipeContext,
+  key: string,
+): RepositoryConfig[] {
+  const parsed = repositoryConfig.array().min(1).safeParse(ctx.config[key]);
+  return parsed.success ? parsed.data : [];
+}
+
+/** 仓库默认分支由其声明决定，所有运行模式均执行配置的初始化命令。 */
+export function worktreeOptions(repository: RepositoryConfig, baseRef?: string): { baseRef?: string } {
+  return {
+    ...(baseRef ? { baseRef } : repository.default_branch ? { baseRef: repository.default_branch } : {}),
+  };
+}
+
+/** 正常变更沿用仓库 hook；测试 smoke 工件已有独立 node:test 证据，才跳过 hook。 */
+export function commitOptions(row: Record<string, unknown>): { noVerify: true } | undefined {
+  return isTestDemand(row) ? { noVerify: true } : undefined;
+}
+
+export function appendArtifact(previous: unknown, line: string): string {
+  const current = text(previous);
+  return current.includes(line)
+    ? current
+    : [current, line].filter(Boolean).join("\n");
+}
+
+export function hasStageTransition(
+  previous: unknown,
+  itemId: string,
+  stage: string,
+): boolean {
+  return text(previous).split("\n").includes(`${itemId}+${stage}`);
+}
+
+export function appendStageTransition(
+  previous: unknown,
+  itemId: string,
+  stage: string,
+): string {
+  const transition = `${itemId}+${stage}`;
+  const audit = text(previous);
+  return audit.split("\n").includes(transition)
+    ? audit
+    : [audit, transition].filter(Boolean).join("\n");
+}
+
+/** 「当前步骤」是引擎持久化的唯一 recipe 指针，必须与本轮 ctx.stepId 一致。 */
+export function isCurrentRecipe(
+  row: Record<string, unknown>,
+  stepId: string,
+): boolean {
+  return recordValue(row, "当前步骤") === stepId;
+}
+
+export function sessionMap(value: unknown): Record<string, string> {
+  if (typeof value !== "string" || !value.trim()) return {};
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return {};
+    return Object.fromEntries(
+      Object.entries(parsed).filter(
+        (entry): entry is [string, string] => typeof entry[1] === "string",
+      ),
+    );
+  } catch {
+    return {};
+  }
+}
+
+export function saveSession(
+  previous: unknown,
+  key: string,
+  result: CodingRunResult,
+): string {
+  const sessions = sessionMap(previous);
+  if (result.sessionId) sessions[key] = result.sessionId;
+  return JSON.stringify(sessions);
+}
+
+/**
+ * Agent 成功返回后先写入 session，再执行可能失败的 Git/CR 后置操作。
+ * 这样重试至少能复用 Agent 上下文，不会因后置操作失败丢失本轮 session。
+ */
+export async function persistCodingSession(
+  ctx: RecipeContext,
+  row: Record<string, unknown>,
+  sessionKey: string,
+  result: CodingRunResult,
+): Promise<string> {
+  if (!result.sessionId) return text(row["Agent会话ID"]);
+  const next = saveSession(row["Agent会话ID"], sessionKey, result);
+  if (next !== text(row["Agent会话ID"])) {
+    await ctx.toolkit.table.updateCurrentRow({ Agent会话ID: next });
+  }
+  return next;
+}
+
+/** 截断长文本，避免失败详情把表单元格 / trace 撑爆（参考事件日志写爆的教训）。 */
+function clip(value: string, max: number): string {
+  const s = value.trim();
+  return s.length <= max ? s : `${s.slice(0, max)}…(+${s.length - max}字)`;
+}
+
+/**
+ * 把失败的 CodingRunResult 展开成可读诊断行，写进 trace logs 与阻塞原因。
+ * 引擎超时/异常时 `result.response` 才是真正的失败文本（如「coding agent 执行超时 (600000ms)」），
+ * 只记一句「Agent 未完成」会让 trace 无法定位根因。
+ */
+export function describeCodingFailure(result: CodingRunResult): string[] {
+  const lines: string[] = [];
+  if (result.failure) {
+    lines.push(`failure.kind=${result.failure.kind}`);
+    const msg = text(result.failure.message);
+    if (msg) lines.push(`failure.message=${clip(msg, 400)}`);
+  }
+  const resp = text(result.response);
+  if (resp) lines.push(`agent.response=${clip(resp, 600)}`);
+  lines.push(
+    result.sessionId
+      ? `sessionId=${result.sessionId}（可续跑）`
+      : "sessionId=none（引擎未回传，重试将冷启动而非续跑）",
+  );
+  return lines;
+}
+
+/**
+ * Agent 主动提出的问题与运行故障必须区分：前者等待真人答复，后者交回引擎重试。
+ * 否则会产生既无问题、又不在候选集内的永久 blocked 记录。
+ */
+export async function handleCodingFailure(
+  ctx: RecipeContext,
+  row: Record<string, unknown>,
+  stage: string,
+  sessionKey: string,
+  result: CodingRunResult,
+  reason: string,
+): Promise<RecipeResult> {
+  const persisted = {
+    Agent会话ID: saveSession(row["Agent会话ID"], sessionKey, result),
+  };
+  const nativeQuestion = text(result.response).match(
+    /^ASK_HUMAN_DETECTED:\s*([\s\S]+)$/,
+  )?.[1];
+  const questions = agentQuestions(result.response, stage);
+  if (nativeQuestion && !questions.length) {
+    questions.push({ id: `${stage}-Q1`, question: nativeQuestion.trim() });
+  }
+  if (questions.length) {
+    return blockExecution(
+      ctx,
+      `${stage} 阶段需要人工答复`,
+      "在人工答复中按问题编号逐项回答后自动续跑",
+      questionsText(questions),
+      persisted,
+    );
+  }
+  const detail = describeCodingFailure(result);
+  const headline = result.failure
+    ? `${result.failure.kind}: ${clip(text(result.failure.message), 160)}`
+    : clip(text(result.response), 160);
+  const executionTimedOut = [text(result.failure?.message), text(result.response)].some(
+    (message) => /^coding agent 执行超时 \(\d+ms\)$/.test(message)
+      || /^错误：等待超时（\d+s），任务可能仍在运行。$/.test(message),
+  );
+  if (!result.sessionId && executionTimedOut) {
+    return blockExecution(
+      ctx,
+      headline ? `${reason}｜${headline}` : reason,
+      "执行超时且未保存 Agent session；请调整 timeoutMs 或人工确认后重试",
+      undefined,
+      persisted,
+    );
+  }
+  const resumeCondition = result.sessionId
+    ? "引擎将使用已保存的 Agent session 自动重试"
+    : "引擎未回传 session，重试将冷启动；若为执行超时，需在 coding.run 传入更大的 timeoutMs";
+  await ctx.toolkit.table.updateCurrentRow({
+    状态: "active",
+    阻塞原因: headline ? `${reason}｜${headline}` : reason,
+    解除条件: resumeCondition,
+    ...persisted,
+  });
+  return failed(reason, detail);
+}
+
+export function blocked(
+  blockReason: string,
+  output: Record<string, unknown> = {},
+): RecipeResult {
+  return { status: "blocked", blockReason, output, logs: [blockReason] };
+}
+
+/** 阻塞字段与引擎 blocked 结果必须同时写出，避免状态和人工可读原因脱节。 */
+export async function blockExecution(
+  ctx: RecipeContext,
+  reason: string,
+  condition: string,
+  questions?: string,
+  extra: Record<string, unknown> = {},
+): Promise<RecipeResult> {
+  await ctx.toolkit.table.updateCurrentRow({
+    状态: "blocked",
+    阻塞原因: reason,
+    解除条件: condition,
+    ...(questions ? { AI问题: questions } : {}),
+    ...extra,
+  });
+  return blocked(reason);
+}
+
+/**
+ * CR 和外部评审进展仍需由当前 recipe 轮询，所以不能把记录转为 blocked。
+ * 仅回写发生变化的可读等待事实，避免每轮检查反复触发表内自动化。
+ */
+export async function waitForExternalProgress(
+  ctx: RecipeContext,
+  row: Record<string, unknown>,
+  reason: string,
+  condition: string,
+  extra: Record<string, unknown> = {},
+): Promise<RecipeResult> {
+  const desired = {
+    状态: "active",
+    阻塞原因: reason,
+    解除条件: condition,
+    ...extra,
+  };
+  const changed = Object.fromEntries(
+    Object.entries(desired).filter(([field, value]) => row[field] !== value),
+  );
+  if (Object.keys(changed).length) {
+    await ctx.toolkit.table.updateCurrentRow(changed);
+  }
+  return {
+    status: "needs_human",
+    blockReason: reason,
+    output: {},
+    logs: [reason],
+  };
+}
+
+export type SdlcQuestion = { id: string; question: string };
+
+export type SdlcAnswer = { id: string; answer: string };
+
+/** 按括号配平提取 `SDLC_QUESTIONS=[...]` 的完整 JSON 数组。
+ * 问题文本里可能出现 `]`（如 "[+ viewId]"），非贪婪正则会在第一个 `]` 截断，
+ * 导致 JSON.parse 失败并静默丢弃全部问题；这里在字符串内忽略括号、跨字符串配平。 */
+function extractQuestionsArray(response: string): string | undefined {
+  const start = response.indexOf("SDLC_QUESTIONS=");
+  if (start < 0) return undefined;
+  const open = response.indexOf("[", start);
+  if (open < 0) return undefined;
+  let depth = 0;
+  let inString = false;
+  let escaped = false;
+  for (let i = open; i < response.length; i++) {
+    const ch = response[i];
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    else if (ch === "[") depth++;
+    else if (ch === "]") {
+      depth--;
+      if (depth === 0) return response.slice(open, i + 1);
+    }
+  }
+  return undefined;
+}
+
+/** Agent 最终回复的机器可读问题清单；Git 工件仍是人类审阅真源。 */
+export function agentQuestions(response: string, stage: string): SdlcQuestion[] {
+  const marker = extractQuestionsArray(response);
+  if (!marker) return [];
+  try {
+    const parsed: unknown = JSON.parse(marker);
+    if (!Array.isArray(parsed)) return [];
+    return parsed
+      .map((value, index): SdlcQuestion | undefined => {
+        if (typeof value === "string" && value.trim()) {
+          return { id: `${stage}-Q${index + 1}`, question: value.trim() };
+        }
+        if (!value || typeof value !== "object" || Array.isArray(value)) return undefined;
+        const item = value as Record<string, unknown>;
+        const id = text(item.id) || `${stage}-Q${index + 1}`;
+        const question = text(item.question);
+        return question ? { id, question } : undefined;
+      })
+      .filter((question): question is SdlcQuestion => Boolean(question));
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 「AI问题」是人工填写入口，不暴露内部 JSON 协议。
+ * 每次阻塞都会在消费后清空问题与答复，因此 Q1、Q2 可在不同阶段安全复用。
+ */
+export function questionsText(questions: SdlcQuestion[]): string {
+  return questions
+    .map((question, index) => `Q${index + 1}: ${question.question}`)
+    .join("\n");
+}
+
+export function parseQuestions(value: unknown): SdlcQuestion[] {
+  const source = text(value);
+  if (!source) return [];
+  try {
+    const parsed: unknown = JSON.parse(source);
+    if (Array.isArray(parsed)) {
+      return parsed
+        .filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object" && !Array.isArray(item))
+        .map((item) => ({ id: text(item.id), question: text(item.question) }))
+        .filter((item) => item.id && item.question);
+    }
+  } catch {
+    // 兼容早期按「1. 问题」保存的记录，迁移时不丢掉在途问题。
+  }
+  return source.split("\n").flatMap((line, index) => {
+    const match = line.match(/^\s*(?:\[([^\]]+)\]|(Q?\d+)[.、:：])\s*(.+)$/i);
+    return match ? [{ id: match[1] || match[2] || `legacy-Q${index + 1}`, question: match[3]!.trim() }] : [];
+  });
+}
+
+export function parseAnswers(value: unknown): SdlcAnswer[] {
+  const source = text(value);
+  if (!source) return [];
+  try {
+    const parsed: unknown = JSON.parse(source);
+    if (Array.isArray(parsed)) {
+      return parsed
+        .filter((item): item is Record<string, unknown> => Boolean(item) && typeof item === "object" && !Array.isArray(item))
+        .map((item) => ({ id: text(item.id), answer: text(item.answer) }))
+        .filter((item) => item.id && item.answer);
+    }
+  } catch {
+    // 同时兼容「问题编号: 答复」的人类易读输入。
+  }
+  return source.split("\n").flatMap((line) => {
+    const match = line.match(/^\s*([^:：]+)[:：]\s*(.+)$/);
+    return match ? [{ id: match[1]!.trim(), answer: match[2]!.trim() }] : [];
+  });
+}
+
+export function unansweredQuestions(questionsValue: unknown, answersValue: unknown): SdlcQuestion[] {
+  const answered = new Set(parseAnswers(answersValue).map((answer) => answer.id));
+  return parseQuestions(questionsValue).filter((question) => !answered.has(question.id));
+}
+
+export function answersForQuestions(questionsValue: unknown, answersValue: unknown): string {
+  const wanted = new Set(parseQuestions(questionsValue).map((question) => question.id));
+  return JSON.stringify(parseAnswers(answersValue).filter((answer) => wanted.has(answer.id)));
+}
+
+export async function consumeAnswersOrBlock(
+  ctx: RecipeContext,
+  row: Record<string, unknown>,
+): Promise<{ answers: string; blocked?: RecipeResult }> {
+  const questions = parseQuestions(row["AI问题"]);
+  if (!questions.length) return { answers: "[]" };
+  const unanswered = unansweredQuestions(row["AI问题"], row["人工答复"]);
+  if (unanswered.length) {
+    return {
+      answers: "[]",
+      blocked: await blockExecution(
+        ctx,
+        "存在待确认问题",
+        `请在人工答复中回答：${unanswered.map((question) => question.id).join("、")}`,
+        questionsText(unanswered),
+      ),
+    };
+  }
+  const answers = answersForQuestions(row["AI问题"], row["人工答复"]);
+  // 消费后必须连「人工答复」一起清空：问题编号会跨轮复用，
+  // 残留旧答复会让下一轮同编号问题被旧答案静默通过。
+  await ctx.toolkit.table.updateCurrentRow({
+    状态: "active",
+    阻塞原因: "",
+    解除条件: "",
+    AI问题: "",
+    人工答复: "",
+  });
+  return { answers };
+}
+
+function handledCommentMarker(stage: string, mrId: string, commentId: number): string {
+  return `CR评论已处理:${stage}:!${mrId}:${commentId}`;
+}
+
+function hasHandledComment(previous: unknown, stage: string, mrId: string, comment: MrComment): boolean {
+  const artifacts = text(previous);
+  return artifacts.split("\n").includes(handledCommentMarker(stage, mrId, comment.id));
+}
+
+/** 返回本轮真正需要 Agent 处理的评论，避免已处理评论随批次变化被重复修复。 */
+export function unhandledComments(
+  previous: unknown,
+  stage: string,
+  mrId: string,
+  comments: MrComment[],
+): MrComment[] {
+  return comments.filter((comment) => !hasHandledComment(previous, stage, mrId, comment));
+}
+
+export function hasHandledComments(previous: unknown, stage: string, mrId: string, comments: MrComment[]): boolean {
+  return unhandledComments(previous, stage, mrId, comments).length === 0;
+}
+
+export function appendHandledComments(previous: unknown, stage: string, mrId: string, comments: MrComment[]): string {
+  return comments.reduce(
+    (artifacts, comment) => appendArtifact(artifacts, handledCommentMarker(stage, mrId, comment.id)),
+    text(previous),
+  );
+}
+
+export function failed(error: string, extraLogs: string[] = []): RecipeResult {
+  return {
+    status: "failed",
+    error,
+    retryable: true,
+    output: {},
+    logs: [error, ...extraLogs.filter(Boolean)],
+  };
+}
+
+export function success(
+  output: Record<string, unknown> = {},
+  message = "阶段工件已提交",
+): RecipeResult {
+  return { status: "success", output, logs: [message] };
+}
+
+export function changeId(row: Record<string, unknown>): string {
+  return recordValue(row, "变更编号");
+}
+
+/**
+ * a1 codeReview 的 `--repo` 需要 `group/project` 形式的仓库路径，
+ * 而 recipe 手里只有 clone URL；传本地 worktree 目录会让 a1 报 NOT_FOUND「代码库不存在」。
+ * 这里从常见 git URL 形态解析出 group/project，已是路径形态时原样返回。
+ */
+export function repoPathFromUrl(url: string): string {
+  const value = text(url).replace(/\.git$/i, "");
+  if (!value) return "";
+  const scp = value.match(/^[^@/]+@[^:]+:(.+)$/);
+  if (scp) return scp[1]!;
+  const http = value.match(/^[a-z]+:\/\/[^/]+\/(.+)$/i);
+  if (http) return http[1]!;
+  return value;
+}
+
+/** MR 标题应是人能读懂的需求标题，而不是变更编号；编号已由分支名承载。 */
+export function changeTitle(row: Record<string, unknown>, fallback: string): string {
+  return recordValue(row, "标题") || recordValue(row, "需求") || fallback;
+}
+
+export function crId(link: unknown): string | undefined {
+  const value = text(link);
+
+  // a1 的详情页路径携带可供 status/comment 等子命令使用的全局 MR ID。
+  // 人工将「当前CR链接」改成纯 URL 以供自动化按钮直达时，不能再依赖 !123 文本标记。
+  const detailUrl = value.match(/\/codereview\/(\d+)(?:[/?#]|$)/i);
+  if (detailUrl) return detailUrl[1];
+
+  const legacy = value.match(/(?:!|mrId=)(\d+)/i);
+  return legacy?.[1];
+}
+
+export type CrEntry = { repoUrl: string; mrId: string; mrUrl: string };
+
+/** 当前阶段可有多个仓库 CR；字段保持人可读 Markdown，解析只接受本项目生成的格式。 */
+export function crEntries(value: unknown): CrEntry[] {
+  return text(value)
+    .split("\n")
+    .map((line) => line.match(/^- \[[^\]]+\]\((.+)\)$/))
+    .filter((match): match is RegExpMatchArray => Boolean(match))
+    .flatMap((match) => {
+      const mrUrl = match[1]!;
+      const detail = mrUrl.match(/\/([^/]+\/[^/]+)\/codereview\/(\d+)(?:[/?#]|$)/i);
+      if (!detail) return [];
+      return [{ repoUrl: detail[1]!, mrId: detail[2]!, mrUrl }];
+    });
+}
+
+export function formatCrEntries(entries: CrEntry[]): string {
+  return entries
+    .map((entry) => {
+      const repo = repoPathFromUrl(entry.repoUrl).split("/").at(-1) || entry.repoUrl;
+      return `- [${repo}](${entry.mrUrl})`;
+    })
+    .join("\n");
+}
+
+/** 评审修复后的用户通知正文：按仓库分别报告评论数，链接仍由当前 CR 字段统一展示。 */
+export function commentRepairNotice(
+  entries: Array<Pick<CrEntry, "repoUrl" | "mrUrl"> & { commentCount: number }>,
+): string {
+  return entries
+    .map((entry) => {
+      const repo = repoPathFromUrl(entry.repoUrl).split("/").at(-1) || entry.repoUrl;
+      return `${repo}：本轮已修复${entry.commentCount}条评论、已推送，等待复审`;
+    })
+    .join("\n");
+}
+
+/** 提取 coding 工件中供同仓库 CR 描述复用的改动详情，不能退回 Agent 自由回复。 */
+export function buildChangeDetails(markdown: string): string | undefined {
+  const heading = /^##\s+改动内容.*$/m.exec(markdown);
+  if (!heading || heading.index === undefined) return undefined;
+  const bodyStart = heading.index + heading[0].length;
+  const remainder = markdown.slice(bodyStart);
+  const nextHeading = /^#{1,2}\s+/m.exec(remainder);
+  const content = remainder.slice(0, nextHeading?.index).trim();
+  return content || undefined;
+}
+
+// ─── 有界重试 ────────────────────────────────────────────
+
+/** 评审修复最大轮次，超过则升级人工处理 */
+export const MAX_REVIEW_ROUNDS = 3;
+
+/**
+ * 安全解析审查轮次，防止 NaN 导致有界重试保护静默失效。
+ * ?? 仅处理 null/undefined，空字符串或非数字字符串会使 Number() 返回 NaN，
+ * 而 NaN > MAX_REVIEW_ROUNDS 永远为 false，守卫永远不会触发。
+ */
+export function parseReviewRound(row: Record<string, unknown>): number {
+  const parsed = Number(row["审查轮次"] ?? 1);
+  return Number.isFinite(parsed) ? parsed : 1;
+}

package/templates/ai-native-sdlc/npmrc

@@ -0,0 +1 @@
+registry=https://registry.npmjs.org/

package/templates/ai-native-sdlc/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "ai-native-sdlc-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "AI Native SDLC 双数字员工协作台",
+  "scripts": {
+    "run": "aitable-workflow run",
+    "setup": "aitable-workflow setup",
+    "check": "aitable-workflow validate",
+    "test": "node --import tsx --test \"test/**/*.test.ts\""
+  },
+  "dependencies": {
+    "aitable-workflow-core": "0.1.28-beta.1789632452666",
+    "tsx": "^4.20.6",
+    "yaml": "^2.8.1",
+    "zod": "^4.1.13"
+  }
+}