@guanlin4924/devflow-pi 0.1.98 → 0.1.99

package/src/mcp/core.ts

@@ -45,33 +45,32 @@ export const runPython: CoreRunner = async (script, args, cwd, stdin, timeoutMs
   const timeoutPromise = new Promise<"timeout">(resolve => {
     timeoutHandle = setTimeout(() => resolve("timeout"), timeoutMs);
   });
-  const exitPromise = child.exited.then(exitCode => ({ exitCode }));
-  const winner = await Promise.race([exitPromise, timeoutPromise]);
-  if (winner === "timeout") {
-    timedOut = true;
-    terminateProcessGroup(child.pid, "SIGTERM");
-    try { child.kill("SIGTERM"); } catch { /* already exited */ }
-    await new Promise(resolve => setTimeout(resolve, TERMINATION_GRACE_MS));
-    terminateProcessGroup(child.pid, "SIGKILL");
-    try { child.kill("SIGKILL"); } catch { /* already exited */ }
+  // The parent can exit while descendants still hold its output pipes open.
+  // Keep the deadline active until both exit and output collection complete.
+  const completion = Promise.all([child.exited, stdoutPromise, stderrPromise])
+    .then(([exitCode, stdout, stderr]) => ({ exitCode, stdout, stderr }));
+  try {
+    const winner = await Promise.race([completion, timeoutPromise]);
+    if (winner === "timeout") {
+      timedOut = true;
+      terminateProcessGroup(child.pid, "SIGTERM");
+      try { child.kill("SIGTERM"); } catch { /* already exited */ }
+      await new Promise(resolve => setTimeout(resolve, TERMINATION_GRACE_MS));
+      terminateProcessGroup(child.pid, "SIGKILL");
+      try { child.kill("SIGKILL"); } catch { /* already exited */ }
+      return {
+        exitCode: null,
+        stdout: await settleText(stdoutPromise, 100),
+        stderr: await settleText(stderrPromise, 100),
+        timedOut,
+      };
+    }
+
+    return { ...winner, timedOut };
+  } finally {
     if (progressTimer !== undefined) clearInterval(progressTimer);
     clearTimeout(timeoutHandle);
-    return {
-      exitCode: null,
-      stdout: await settleText(stdoutPromise, 100),
-      stderr: await settleText(stderrPromise, 100),
-      timedOut,
-    };
   }
-
-  if (progressTimer !== undefined) clearInterval(progressTimer);
-  clearTimeout(timeoutHandle);
-  return {
-    exitCode: winner.exitCode,
-    stdout: await stdoutPromise,
-    stderr: await stderrPromise,
-    timedOut,
-  };
 };
 
 export async function invokeCore(

package/src/mcp/server.ts

@@ -114,20 +114,19 @@ export async function createMcpServer(options: McpServerOptions) {
       if (tool === "run_feature" && running) throw new McpError("mcp_busy", "another run_feature is in progress");
 
       if (tool === "run_feature") {
-        const bindingFile = path.join(auth.project, ".devflow/planning/features", String(feature), "acceptance-test-bindings.json");
-        let bindings: unknown;
-        try {
-          bindings = JSON.parse(await readFile(bindingFile, "utf8"));
-        } catch {
-          throw new McpError("mcp_input_invalid", "acceptance-test-bindings.json is missing or invalid");
-        }
-        const profiles = collectEnvironmentProfiles(bindings);
-        if ([...profiles].some(profile => !auth.grant.environment_profiles.includes(profile))) {
-          throw new McpError("mcp_environment_not_allowed", "environment profile is not authorized");
-        }
-
         running = true;
         try {
+          const bindingFile = path.join(auth.project, ".devflow/planning/features", String(feature), "acceptance-test-bindings.json");
+          let bindings: unknown;
+          try {
+            bindings = JSON.parse(await readFile(bindingFile, "utf8"));
+          } catch {
+            throw new McpError("mcp_input_invalid", "acceptance-test-bindings.json is missing or invalid");
+          }
+          const profiles = collectEnvironmentProfiles(bindings);
+          if ([...profiles].some(profile => !auth.grant.environment_profiles.includes(profile))) {
+            throw new McpError("mcp_environment_not_allowed", "environment profile is not authorized");
+          }
           const runResult = await invokeCore(
             runner,
             "run",

package/src/project-context.ts

@@ -138,6 +138,10 @@ export async function assertPlanningBoundary(root: string): Promise<string> {
 }
 
 export async function loadProjectContext(root: string): Promise<ProjectContext> {
+  return readProjectContext(root, false);
+}
+
+async function readProjectContext(root: string, registerWorkspace: boolean): Promise<ProjectContext> {
   const canonicalRoot = await canonicalDirectory(root);
   const manifestPath = projectLayout(canonicalRoot).manifestPath;
   const manifestValue = JSON.parse(await readFile(manifestPath, "utf8")) as Record<string, unknown>;
@@ -150,6 +154,10 @@ export async function loadProjectContext(root: string): Promise<ProjectContext>
   const manifest = validateManifest(manifestValue, manifestPath);
   await mkdir(projectLayout(canonicalRoot).planningRoot, { recursive: true });
   const planningRoot = await assertPlanningBoundary(canonicalRoot);
+  if (registerWorkspace) {
+    const store = await InitializationStore.open({ root: canonicalRoot, manifest });
+    try { await store.registerWorkspace(); } finally { store.close(); }
+  }
   if (!(await exists(projectControlDatabasePath(manifest.projectId)))) throw new Error("Project initialization database is not registered; run explicit project initialization first");
   return attachInitializationStore({ root: canonicalRoot, manifestPath, manifest, planningRoot });
 }
@@ -198,7 +206,7 @@ export async function initializeProject(root: string): Promise<{ context: Projec
   await mkdir(devflowDir, { recursive: true });
   await assertPlanningBoundary(canonicalRoot);
   if (await exists(manifestPath)) {
-    const context = await loadProjectContext(canonicalRoot);
+    const context = await readProjectContext(canonicalRoot, true);
     await ensureTestRuntimeLayout(canonicalRoot, context.planningRoot);
     return { context, created: false };
   }

package/src/project-initializer.ts

@@ -42,7 +42,7 @@ function source(file: SourceFile, kind: FactKind, objectKey: string, value: Reco
   return { kind, objectKey, repository: file.repository, value, evidenceLevel: "observed", sourcePath: file.path, sourceLine: line, sourceFingerprint: file.contentHash, extractor, confidence: "heuristic" };
 }
 
-async function walk(repository: string, repositoryRoot: string, includes: string[], excludes: string[], diagnostics: ScanDiagnostic[], relative = ""): Promise<SourceFile[]> {
+async function walk(repository: string, repositoryRoot: string, includes: string[], excludes: string[], diagnostics: ScanDiagnostic[], maxFileSize: number, relative = ""): Promise<SourceFile[]> {
   const directory = path.join(repositoryRoot, relative);
   let entries;
   try { entries = await readdir(directory, { withFileTypes: true }); }
@@ -54,11 +54,11 @@ async function walk(repository: string, repositoryRoot: string, includes: string
     const child = path.join(relative, entry.name);
     const normalized = child.replaceAll("\\", "/");
     if (excludes.some(pattern => globMatches(normalized, pattern) || globMatches(`${normalized}/`, pattern))) { if (diagnostics.length < 1000) diagnostics.push({ repository, path: normalized, reason: "excluded" }); continue; }
-    if (entry.isDirectory()) { result.push(...await walk(repository, repositoryRoot, includes, excludes, diagnostics, child)); continue; }
+    if (entry.isDirectory()) { result.push(...await walk(repository, repositoryRoot, includes, excludes, diagnostics, maxFileSize, child)); continue; }
     if (!entry.isFile()) continue;
     if (includes.length && !includes.some(pattern => globMatches(normalized, pattern))) continue;
     const absolute = path.join(repositoryRoot, child); const info = await stat(absolute);
-    if (info.size > 2 * 1024 * 1024) { diagnostics.push({ repository, path: normalized, reason: "too_large" }); continue; }
+    if (info.size > maxFileSize) { diagnostics.push({ repository, path: normalized, reason: "too_large" }); continue; }
     let bytes: Buffer;
     try { bytes = await readFile(absolute); }
     catch (error) { diagnostics.push({ repository, path: normalized, reason: "unreadable", message: error instanceof Error ? error.message : String(error) }); continue; }
@@ -84,7 +84,7 @@ async function scan(context: ProjectContext, config: ScanConfigInput): Promise<{
     const root = path.resolve(context.root, repository.relativePath);
     if (!path.isAbsolute(repository.relativePath) && root !== context.root && !root.startsWith(`${context.root}${path.sep}`)) throw new Error(`Repository escapes project root: ${repository.relativePath}`);
     repositoryVersions.push({ repository: repository.name, revision: await gitRevision(root) });
-    all.push(...await walk(repository.name, root, includes, excludes, diagnostics));
+    all.push(...await walk(repository.name, root, includes, excludes, diagnostics, config.maxFileSize ?? 2 * 1024 * 1024));
   }
   return { files: all.sort((a, b) => `${a.repository}/${a.path}`.localeCompare(`${b.repository}/${b.path}`)), diagnostics, repositoryVersions };
 }

package/src/session-rollover.ts

@@ -0,0 +1,10 @@
+/** The current prepared revision differs from the immutable handoff's source revision after recovery. */
+export function preparedRolloverRevision(state: Record<string, unknown>): number | undefined {
+  const rollover = state.rollover as Record<string, unknown> | undefined;
+  if (rollover?.status !== "prepared") return undefined;
+  const revision = rollover.prepared_state_revision ?? (
+    typeof rollover.expected_state_revision === "number" ? rollover.expected_state_revision + 1 : undefined
+  );
+  return typeof revision === "number" && Number.isSafeInteger(revision) && revision === state.revision
+    ? revision : undefined;
+}

package/src/workflow-diagnosis.ts

@@ -0,0 +1,407 @@
+/**
+ * User-facing workflow diagnosis for the single "next step" entry.
+ *
+ * Pure functions only: the runtime gathers Core facts (inspector snapshot,
+ * rollover state, output readiness) and this module turns them into a closed
+ * set of Chinese diagnoses with fix actions. Fix actions are executed by
+ * runtime code, never by the model.
+ */
+
+export type FixAction =
+  | "create-feature"
+  | "review-and-advance"
+  | "rerun-step"
+  | "revise-outputs"
+  | "repair-registry"
+  | "resume-rollover"
+  | "help-bundle"
+  | "cancel-feature";
+
+export type DiagnosisCode =
+  | "INSPECT_FAILED"
+  | "NO_ACTIVE_FEATURE"
+  | "WORKFLOW_COMPLETE"
+  | "ROLLOVER_PENDING"
+  | "REGISTRY_DRIFT"
+  | "CHECKPOINT_WAITING"
+  | "STEP_OUTPUTS_READY"
+  | "STATE_INVALID"
+  | "CHECKPOINT_OUTPUTS_MISSING"
+  | "TRACK_BOUNDARY"
+  | "UNKNOWN_NEXT_STEP"
+  | "WORKFLOW_BLOCKED";
+
+export type Diagnosis = {
+  code: DiagnosisCode;
+  title: string;
+  evidence: string[];
+  fixes: FixAction[];
+};
+
+export type DiagnosisKind = "no-feature" | "complete" | "execute" | "review" | "repair" | "blocked";
+
+export type WorkflowDiagnosis = {
+  kind: DiagnosisKind;
+  feature?: string;
+  stepId?: string;
+  stepLabel?: string;
+  progress?: { index: number; total: number };
+  diagnoses: Diagnosis[];
+};
+
+export type DiagnosisInput = {
+  inspect: { ok: boolean; error?: string };
+  snapshot: Record<string, unknown> | null;
+  disposition: "execute" | "review" | "blocked" | "complete" | "idle";
+  /** Every required output of the current step exists and is not marked invalid; `planned` allowed. */
+  outputsReady: boolean;
+  rolloverPrepared: boolean;
+};
+
+export const FIX_LABELS: Record<FixAction, { label: string; description: string }> = {
+  "create-feature": { label: "创建需求", description: "输入需求名称，由 Devflow 创建工作流状态" },
+  "review-and-advance": { label: "审查后推进", description: "弹出推进确认；确认后由 Core 校验产物并推进到下一步" },
+  "rerun-step": { label: "重新执行这一步", description: "按当前步骤重新启动 AI（会先激活执行合同）" },
+  "revise-outputs": { label: "按意见修改产物", description: "回到审查状态；你直接说明要改什么，AI 修改后再推进" },
+  "repair-registry": { label: "修复登记表", description: "由 Core 按当前状态重建产物登记表；不推进工作流" },
+  "resume-rollover": { label: "继续会话交接", description: "完成未走完的会话切换，然后在新会话中继续" },
+  "help-bundle": { label: "生成求助包", description: "把诊断信息写到 .devflow/diagnostics/，不含源码内容" },
+  "cancel-feature": { label: "弃用当前需求", description: "结束当前需求并保留现有产物；之后可以创建新需求" },
+};
+
+const REASON_TITLES: Record<string, string> = {
+  state_validation_failed: "状态文件校验失败，系统无法安全地自动修复",
+  missing_checkpoint_outputs: "检查点需要的产物不完整",
+  unknown_next_step: "找不到下一个可执行的步骤",
+  current_output_registry_drift: "产物登记表和实际文件不一致",
+  track_scope_complete: "当前轨道的步骤已完成，需要切换轨道",
+};
+
+function text(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function record(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+}
+
+function currentStep(snapshot: Record<string, unknown>): Record<string, unknown> | undefined {
+  return record(snapshot.current_step) ?? record(snapshot.next_step);
+}
+
+function outputPaths(step: Record<string, unknown> | undefined): string[] {
+  const outputs = Array.isArray(step?.outputs) ? step.outputs : [];
+  return outputs.flatMap(output => {
+    const item = record(output);
+    if (!item || item.required === false) return [];
+    const resolved = text(item.resolved_path) ?? text(item.path);
+    return resolved ? [`${resolved}${item.exists === true ? " ✓" : "（缺失）"}`] : [];
+  });
+}
+
+function validationEvidence(snapshot: Record<string, unknown>): string[] {
+  const validation = record(snapshot.state_validation);
+  const errors = Array.isArray(validation?.errors) ? validation.errors : [];
+  return errors.slice(0, 5).map(error => {
+    const item = record(error);
+    const code = text(item?.code) ?? "unknown";
+    const message = text(item?.message) ?? text(item?.path) ?? "";
+    return message ? `${code}：${message}` : code;
+  });
+}
+
+function progressOf(snapshot: Record<string, unknown>, stepId: string | undefined): WorkflowDiagnosis["progress"] {
+  const steps = Array.isArray(snapshot.workflow_steps) ? snapshot.workflow_steps : [];
+  const index = steps.findIndex(step => record(step)?.id === stepId);
+  return index >= 0 ? { index: index + 1, total: steps.length } : undefined;
+}
+
+export function diagnoseWorkflow(input: DiagnosisInput): WorkflowDiagnosis {
+  const { snapshot } = input;
+  if (!input.inspect.ok || !snapshot) {
+    return {
+      kind: "blocked",
+      diagnoses: [{
+        code: "INSPECT_FAILED",
+        title: "无法读取工作流状态",
+        evidence: input.inspect.error ? [firstMeaningfulLine(input.inspect.error)] : [],
+        fixes: ["help-bundle"],
+      }],
+    };
+  }
+  const feature = text(snapshot.current_feature);
+  const step = currentStep(snapshot);
+  const stepId = text(step?.id);
+  const base = {
+    feature,
+    stepId,
+    stepLabel: text(step?.label),
+    progress: progressOf(snapshot, stepId),
+  };
+
+  if (input.rolloverPrepared) {
+    return {
+      ...base,
+      kind: "repair",
+      diagnoses: [{ code: "ROLLOVER_PENDING", title: "上一次的会话交接没有走完", evidence: [], fixes: ["resume-rollover"] }],
+    };
+  }
+  if (snapshot.reason === "missing_state_file" || !feature) {
+    return {
+      ...base,
+      kind: "no-feature",
+      diagnoses: [{ code: "NO_ACTIVE_FEATURE", title: "还没有进行中的需求", evidence: [], fixes: ["create-feature"] }],
+    };
+  }
+  if (input.disposition === "complete") {
+    return {
+      ...base,
+      kind: "complete",
+      diagnoses: [{ code: "WORKFLOW_COMPLETE", title: `需求「${feature}」已经结束`, evidence: [], fixes: ["create-feature"] }],
+    };
+  }
+  const plan = record(snapshot.recovery_plan);
+  if (plan?.classification === "safe_repairable") {
+    return {
+      ...base,
+      kind: "repair",
+      diagnoses: [{
+        code: "REGISTRY_DRIFT",
+        title: "产物登记表和当前状态不一致",
+        evidence: text(snapshot.reason) ? [`原因代码：${String(snapshot.reason)}`] : [],
+        fixes: ["repair-registry"],
+      }],
+    };
+  }
+  if (snapshot.action === "await_user_confirmation" && input.disposition === "review") {
+    return {
+      ...base,
+      kind: "review",
+      diagnoses: [{
+        code: "CHECKPOINT_WAITING",
+        title: `检查点${text(snapshot.checkpoint) ? ` ${String(snapshot.checkpoint)}` : ""}正在等待你确认`,
+        evidence: outputPaths(step),
+        fixes: ["review-and-advance", "revise-outputs"],
+      }],
+    };
+  }
+  if (snapshot.action === "blocked" || input.disposition === "blocked" || input.disposition === "idle") {
+    const reason = text(snapshot.reason) ?? "unknown";
+    const code: DiagnosisCode = reason === "state_validation_failed"
+      ? "STATE_INVALID"
+      : reason === "missing_checkpoint_outputs"
+        ? "CHECKPOINT_OUTPUTS_MISSING"
+        : reason === "unknown_next_step"
+          ? "UNKNOWN_NEXT_STEP"
+          : reason === "track_scope_complete"
+            ? "TRACK_BOUNDARY"
+            : "WORKFLOW_BLOCKED";
+    const evidence = [
+      ...(text(snapshot.message) ? [String(snapshot.message)] : []),
+      ...validationEvidence(snapshot),
+      ...(code === "CHECKPOINT_OUTPUTS_MISSING" ? outputPaths(step) : []),
+    ];
+    return {
+      ...base,
+      kind: "blocked",
+      diagnoses: [{
+        code,
+        title: REASON_TITLES[reason] ?? `工作流被阻塞（原因代码：${reason}）`,
+        evidence,
+        fixes: ["help-bundle", "cancel-feature"],
+      }],
+    };
+  }
+  if (snapshot.action === "run_next_step" && input.outputsReady) {
+    return {
+      ...base,
+      kind: "review",
+      diagnoses: [{
+        code: "STEP_OUTPUTS_READY",
+        title: "这一步的产物已经写好，但还没有确认完成",
+        evidence: outputPaths(step),
+        fixes: ["review-and-advance", "revise-outputs", "rerun-step"],
+      }],
+    };
+  }
+  return { ...base, kind: "execute", diagnoses: [] };
+}
+
+export function renderDiagnosis(result: WorkflowDiagnosis): string {
+  const lines: string[] = [];
+  if (result.feature) {
+    const progress = result.progress ? `第 ${result.progress.index}/${result.progress.total} 步` : "当前步骤";
+    const step = result.stepLabel && result.stepId ? `「${result.stepLabel}」（${result.stepId}）` : result.stepId ? `（${result.stepId}）` : "";
+    lines.push(`需求「${result.feature}」，${progress}${step}。`);
+  }
+  if (result.diagnoses.length === 0) {
+    lines.push(result.kind === "execute" ? "没有发现阻塞，可以开始执行这一步。" : "没有发现阻塞。");
+    return lines.join("\n");
+  }
+  for (const diagnosis of result.diagnoses) {
+    lines.push(`发现问题：${diagnosis.title}（${diagnosis.code}）`);
+    for (const item of diagnosis.evidence) lines.push(`- ${item}`);
+    lines.push(`可选处理：${diagnosis.fixes.map(fix => FIX_LABELS[fix].label).join(" / ")}`);
+  }
+  return lines.join("\n");
+}
+
+/** Short phrases that mean "advance the workflow". Exact match only, so design
+ * discussions such as "下一步怎么设计比较好" are never intercepted. */
+const NEXT_STEP_PHRASES = new Set([
+  "下一步", "下一步吧", "进入下一步", "开始下一步", "继续下一步", "执行下一步",
+  "可以下一步不", "可以下一步吗", "可以下一步了吗", "能下一步吗", "往下走", "继续往下",
+]);
+const CONTINUE_PHRASES = new Set(["继续", "继续吧", "继续执行"]);
+
+export function classifyNextStepPhrase(input: string): "next" | "continue" | null {
+  const normalized = input.trim().replace(/[\s。！!？?，,~～.]+$/u, "").replace(/\s+/gu, "");
+  if (NEXT_STEP_PHRASES.has(normalized)) return "next";
+  if (CONTINUE_PHRASES.has(normalized)) return "continue";
+  return null;
+}
+
+type FailureResult = { ok: boolean; exitCode: number | null; stdout: string; stderr: string };
+
+const STACK_FRAME = /^\s*(?:from\s+\S+:\d+:in\b|File\s+".*",\s+line\s+\d+|at\s+\S+\s+\(|\^+\s*$|Traceback \(most recent call last\):)/u;
+
+export function firstMeaningfulLine(raw: string): string {
+  const lines = raw.split(/\r?\n/u).map(line => line.trim()).filter(Boolean);
+  const pythonError = [...lines].reverse().find(line => /^[A-Za-z_.]+(?:Error|Exception):\s/u.test(line));
+  if (lines.some(line => line.startsWith("Traceback")) && pythonError) return pythonError.slice(0, 300);
+  const line = lines.find(item => !STACK_FRAME.test(item)) ?? lines[0] ?? "";
+  // Ruby: "/abs/path/script.rb:17:in `read': message (ErrClass)"
+  const ruby = /^\S+\.rb:\d+:in\s+[`'][^']*':\s*(.+)$/u.exec(line);
+  return (ruby ? ruby[1] : line).slice(0, 300);
+}
+
+function relativeDevflowPath(value: string): string {
+  const index = value.indexOf(".devflow/");
+  return index >= 0 ? value.slice(index) : value;
+}
+
+/**
+ * Chinese summary for a failed or empty non-JSON tool result. Returns null for
+ * JSON output, which the model and tests parse as-is.
+ */
+export function summarizeToolFailure(result: FailureResult): string | null {
+  const raw = (result.stderr || result.stdout || "").trim();
+  if (result.ok) return raw ? null : "工具执行成功，但没有返回任何结果。";
+  if (!raw) return `工具执行失败，没有输出任何信息（退出码 ${String(result.exitCode)}）。`;
+  try {
+    JSON.parse(result.stdout || result.stderr);
+    return null;
+  } catch {
+    // Plain text or a stack trace: summarize below.
+  }
+  const line = firstMeaningfulLine(raw);
+  const missing = /No such file or directory(?:\s*@\s*\w+)?\s*-\s*(\S+)/u.exec(raw)?.[1];
+  if (missing && /\.devflow\/planning\/STATE\.md$/u.test(missing)) {
+    return "还没有创建需求：项目中没有 .devflow/planning/STATE.md。请告诉用户先创建需求（说「下一步」，或运行 /devflow start <需求名>），不要自行创建该文件。";
+  }
+  if (missing) return `需要的文件不存在：${relativeDevflowPath(missing)}`;
+  const activeStep = /requires the active ([\w-]+) step/u.exec(raw)?.[1];
+  if (activeStep) {
+    return `该操作只能在「${activeStep}」步骤中执行，当前不在该步骤。请告诉用户说「下一步」，由 Devflow 推进到对应步骤后再执行。`;
+  }
+  const required = /^([\w-]+(?:\s*,\s*[\w-]+)*)\s+(?:is|are)\s+required\b/u.exec(line)?.[1]
+    ?? /\brequires?\s+(?:a\s+|an\s+)?([\w-]+)\s*$/u.exec(line)?.[1];
+  if (required) return `缺少参数：${required}（原始信息：${line}）`;
+  return `工具执行失败：${line}`;
+}
+
+const CONTROL_REASONS: Record<string, string> = {
+  stale_revision: "状态刚被其他操作更新过（版本号不一致）。请重新说「下一步」，按最新状态处理。",
+  missing_state_file: "还没有创建需求。",
+  missing_state_front_matter: "状态文件格式损坏，请运行 /devflow fix 生成求助包。",
+  unknown_step: "要推进的步骤和当前步骤对不上。请重新说「下一步」。",
+  gate_current_step_mismatch: "要推进的步骤和当前步骤对不上。请重新说「下一步」。",
+  gate_target_step_unknown: "目标步骤不在当前工作流中。",
+  feature_not_active: "产物所属的需求不是当前进行中的需求。",
+  session_rollover_in_progress: "会话交接还没完成。请说「下一步」继续交接。",
+  state_validation_failed: "状态文件校验失败。请运行 /devflow fix 查看详情。",
+  not_waiting_checkpoint: "当前不在等待确认的检查点。",
+  no_pending_step: "已经没有待执行的步骤了。",
+  acceptance_results_not_passed: "验收测试结果没有全部通过，请先处理失败的用例。",
+  dsl_not_approved: "有验收脚本尚未批准，请在 /devflow control 中批准。",
+  environment_profile_not_approved: "测试环境配置尚未批准，请在 /devflow control 中批准。",
+  approval_invalid: "批准记录无效或已过期，请在 /devflow control 中重新批准。",
+  human_result_unapproved: "人工验收结论尚未批准，请在 /devflow control 中处理。",
+  cancel_reason_required: "弃用需求需要填写原因。",
+};
+
+/** Chinese explanation of a failed control-plane transition (advance_state.rb and friends). */
+export function describeControlFailure(result: FailureResult): string {
+  let payload: Record<string, unknown> | undefined;
+  try {
+    payload = record(JSON.parse(result.stdout || result.stderr || ""));
+  } catch {
+    payload = undefined;
+  }
+  if (!payload) return summarizeToolFailure(result) ?? "未知错误。";
+  const reason = text(payload.reason) ?? text(record(payload.error)?.code) ?? "unknown";
+  const known = CONTROL_REASONS[reason];
+  const details = payload.details ?? payload.errors ?? payload.issues;
+  const detailText = details === undefined ? "" : JSON.stringify(details).slice(0, 400);
+  return [
+    known ?? `未通过推进校验（原因代码：${reason}）。`,
+    ...(detailText && detailText !== "{}" && detailText !== "[]" ? [`详情：${detailText}`] : []),
+  ].join("\n");
+}
+
+export type ToolFailureRecord = { at: string; tool: string; exitCode: number | null; summary: string; raw: string };
+
+export type HelpBundleInput = {
+  version: string;
+  createdAt: string;
+  diagnosis: WorkflowDiagnosis;
+  snapshot: Record<string, unknown> | null;
+  inspectError?: string;
+  doctor?: Array<{ id: string; status: string; message: string }>;
+  rollover?: Record<string, unknown> | null;
+  failures: ToolFailureRecord[];
+  /** Absolute prefixes replaced by "." and "~" so the bundle stays project-relative. */
+  root?: string;
+  home?: string;
+};
+
+function sanitizePaths(value: string, root: string | undefined, home: string | undefined): string {
+  let result = value;
+  if (root) result = result.split(root.endsWith("/") ? root : `${root}/`).join("./").split(root).join(".");
+  if (home) result = result.split(home).join("~");
+  return result;
+}
+
+/** Bounded, project-relative diagnostic bundle. Never includes source contents. */
+export function buildHelpBundle(input: HelpBundleInput): Record<string, unknown> {
+  const snapshot = input.snapshot;
+  const rollover = record(input.rollover?.rollover);
+  return {
+    schema_version: 1,
+    created_at: input.createdAt,
+    devflow_pi_version: input.version,
+    diagnosis: input.diagnosis,
+    state: snapshot ? {
+      feature: snapshot.current_feature ?? null,
+      flow: snapshot.current_flow ?? null,
+      phase: snapshot.current_phase ?? null,
+      status: snapshot.status ?? null,
+      action: snapshot.action ?? null,
+      reason: snapshot.reason ?? null,
+      revision: snapshot.revision ?? null,
+      checkpoint: snapshot.checkpoint ?? null,
+      current_step: record(snapshot.current_step)?.id ?? null,
+      completed_steps: Array.isArray(snapshot.completed_steps) ? snapshot.completed_steps.length : null,
+      pending_steps: Array.isArray(snapshot.pending_steps) ? snapshot.pending_steps.length : null,
+      state_validation_errors: validationEvidence(snapshot),
+    } : null,
+    inspect_error: input.inspectError ? sanitizePaths(firstMeaningfulLine(input.inspectError), input.root, input.home) : null,
+    doctor: input.doctor ?? null,
+    rollover: rollover ? { id: rollover.id ?? null, status: rollover.status ?? null } : null,
+    recent_tool_failures: input.failures.slice(-20).map(failure => ({
+      ...failure,
+      summary: sanitizePaths(failure.summary, input.root, input.home),
+      raw: sanitizePaths(failure.raw, input.root, input.home).slice(0, 2000),
+    })),
+  };
+}