dsh-issue2pr 0.1.0

package/lib/assistant.js

@@ -0,0 +1,137 @@
+// lib/assistant.js — 悬浮智能助手的上下文聚合（每次提问时现读，不落盘不缓存）
+// focus 来自前端 viewStore：{ nav, slug, runId }（用户当前所在页面 / 选中项目 / 选中 Run）
+import { join } from "node:path";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { listProjects, readArtifact } from "./store.js";
+import { loadRun } from "./pipeline.js";
+import { STAGE_DEFS } from "./stageConfig.js";
+
+export const ASSISTANT_SYSTEM_HEAD = [
+  "你是 Issue2PR 插件（运行在 DSH 宿主里）内置的智能助手，悬浮在工作台右上角，",
+  "职责是解答用户对这个工作台的提问、疑惑，以及运行过程中的状态询问。",
+  "",
+  "回答守则：",
+  "1. 回答运行状态类问题（跑到哪了/为什么失败/卡住了吗）时，只依据下方「实时上下文」，不要臆造；上下文里没有的信息就明说「当前上下文里没有」，并建议用户先在项目页选中项目或运行页选中 Run。",
+  "2. 概念类问题（P1-P11 是什么、复核门、外部委托、reviewMode 等）可基于你对插件设计的理解回答，下方附有阶段速查表。",
+  "3. 用户提到「这个项目/这个 Run」时，优先理解为实时上下文里「当前聚焦」的部分。",
+  "4. 用简体中文，简洁直接，先给结论；涉及界面操作的给出具体点击路径（左侧目录：项目/运行/产物/配置/说明）。",
+  "5. 不要编造不存在的功能或数据。",
+].join("\n");
+
+// 上下文总长保护：超出时优先保住「聚焦 Run + 最近事件」（截断在末尾按序丢弃全局部分）
+const MAX_CONTEXT_CHARS = 12000;
+const EVENT_TAIL = 30;
+const EVENT_DETAIL_CHARS = 300;
+
+const NAV_LABELS = {
+  projects: "项目页", runs: "运行页", artifacts: "产物页", config: "配置页", guide: "说明页",
+};
+
+// session/claude 模式外部执行进度（口径与 index.js externalProgress 一致：不 import 是为避免循环依赖）
+function externalProgressOf(runDir) {
+  const dir = join(runDir, "06-implementation", "patches");
+  let patches = 0;
+  if (existsSync(dir)) patches = readdirSync(dir).filter((f) => f.endsWith(".diff")).length;
+  let tasks = null;
+  try { tasks = JSON.parse(readFileSync(join(runDir, "05-task-graph.json"), "utf8")).nodes.length; } catch { /* 缺任务图时只报 patch 数 */ }
+  return { patches, tasks, report: existsSync(join(runDir, "06-implementation", "coder-report.json")) };
+}
+
+// 单项目最近一个 Run 摘要（runId 前缀即时间戳，目录名字典序 = 时间序，取最后一个）
+function latestRunOf(root, slug) {
+  const runsDir = join(root, "projects", slug, "runs");
+  if (!existsSync(runsDir)) return null;
+  const ids = readdirSync(runsDir).filter((id) => existsSync(join(runsDir, id, "run.json"))).sort();
+  if (!ids.length) return null;
+  const run = loadRun(join(runsDir, ids[ids.length - 1]));
+  return run ? { id: run.id, status: run.status, current: run.current, createdAt: run.createdAt, _dir: join(runsDir, ids[ids.length - 1]) } : null;
+}
+
+function stageTable(run) {
+  return STAGES_LINE.map(([id, name, desc]) => {
+    const st = run.stages[id] || {};
+    return `- ${id} ${name}（${desc}）：${st.status || "pending"}`
+      + (st.error ? `，错误: ${String(st.error).slice(0, 200)}` : "");
+  }).join("\n");
+}
+const STAGES_LINE = Object.entries(STAGE_DEFS).map(([id, def]) => [id, def.name, def.desc]);
+
+function eventTail(runDir) {
+  const raw = readArtifact(runDir, "trace/events.jsonl");
+  if (!raw) return [];
+  const lines = raw.split("\n").filter((l) => l.trim());
+  return lines.slice(-EVENT_TAIL).map((l) => {
+    try {
+      const e = JSON.parse(l);
+      const detail = String(e.detail == null ? "" : e.detail).slice(0, EVENT_DETAIL_CHARS);
+      return `[${String(e.at || "")}] ${e.stage || ""} ${e.name || ""}${e.ok === false ? "（失败）" : ""}${detail ? "\n  " + detail.replace(/\n/g, "\n  ") : ""}`;
+    } catch { return null; }
+  }).filter(Boolean);
+}
+
+export function buildAssistantContext(root, focus = {}) {
+  const out = [];
+  const push = (s) => out.push(s);
+
+  // —— 0. 用户当前位置 ——
+  const navLabel = NAV_LABELS[focus.nav] || (focus.nav ? String(focus.nav) : "未知");
+  push(`## 用户当前位置\n正在看「${navLabel}」；选中项目：${focus.slug || "（未选中）"}；选中 Run：${focus.runId || "（未选中）"}。`);
+
+  // —— 1. 全局：所有项目概要（最多 10 个，每个带最近 Run 状态） ——
+  const projects = listProjects(root);
+  push("\n## 全局：项目概要（共 " + projects.length + " 个）");
+  if (!projects.length) push("（还没有项目。用户可在「项目」页新建。）");
+  for (const p of projects.slice(0, 10)) {
+    const trig = (p.triggers || []).map((t) => t.kind + " " + t.uri).join("；") || "（无）";
+    const last = latestRunOf(root, p.slug);
+    push(`- ${p.name}（slug: ${p.slug}）：reviewMode=${p.reviewMode}，P6 模式=${p.p6Mode}；触发源：${trig}`
+      + (last ? `；最近 Run ${last.id}（${String(last.createdAt || "").slice(0, 19)}）状态=${last.status}，当前阶段=${last.current}` : "；尚无 Run"));
+  }
+
+  // —— 2. 聚焦项目配置摘要 ——
+  if (focus.slug && /^[a-z0-9-]+$/.test(focus.slug)) {
+    const p = projects.find((x) => x.slug === focus.slug);
+    if (p) {
+      const custom = Object.keys(p.stageConfig || {});
+      const repos = (p.repos || []).map((r) => r.uri).join("；");
+      push(`\n## 当前聚焦项目：${p.name}（${p.slug}）`);
+      push(`仓库：${repos}`);
+      push(`reviewMode=${p.reviewMode}（every=每阶段都要人工复核 / key-only=仅关键阶段 / auto=全自动）；P6 模式=${p.p6Mode}（builtin=内置执行 / session=生成任务包等外部会话 / claude=委托 Claude Code CLI）`);
+      push(custom.length ? `已自定义配置的阶段：${custom.join("、")}` : "各阶段均用默认配置");
+    }
+  }
+
+  // —— 3. 聚焦 Run 状态机 + 外部执行进度 + 最近事件 ——
+  if (focus.slug && focus.runId && /^[a-z0-9-]+$/.test(focus.slug) && /^\d{8}-\d{6}-[a-z0-9-]+$/.test(focus.runId)) {
+    const runsDir = join(root, "projects", focus.slug, "runs", focus.runId);
+    const run = loadRun(runsDir);
+    if (run) {
+      push(`\n## 当前聚焦 Run：${run.id}`);
+      push(`状态=${run.status}；当前阶段=${run.current}；创建于 ${run.createdAt}；reviewMode=${run.reviewMode}；P6 模式=${run.p6Mode}；触发源：${run.trigger?.kind || ""} ${run.trigger?.uri || ""}`);
+      if (run.externalExec) {
+        const e = run.externalExec;
+        push(`外部执行：executor=${e.executor || "?"}，status=${e.status || "?"}`
+          + (e.statsSummary ? `，${e.statsSummary}` : "")
+          + (e.error ? `，错误: ${String(e.error).slice(0, 200)}` : ""));
+      }
+      if (run.p6Mode === "session" || run.p6Mode === "claude") {
+        const ep = externalProgressOf(runsDir);
+        push(`外部进度：patch ${ep.patches}${ep.tasks != null ? "/" + ep.tasks : ""} 份，coder-report ${ep.report ? "已生成" : "未生成"}`);
+      }
+      push("\n### 各阶段状态");
+      push(stageTable(run));
+      const evs = eventTail(runsDir);
+      if (evs.length) {
+        push(`\n### 最近事件（${evs.length} 条，按时间序）`);
+        push(evs.join("\n"));
+      }
+    }
+  }
+
+  // —— 4. 概念速查 ——
+  push("\n## 阶段速查表（P1-P11 流水线）");
+  for (const [id, def] of Object.entries(STAGE_DEFS)) push(`- ${id} ${def.name}：${def.desc}`);
+
+  const text = out.join("\n");
+  return text.length > MAX_CONTEXT_CHARS ? text.slice(0, MAX_CONTEXT_CHARS) + "\n…（上下文过长已截断）" : text;
+}

package/lib/connections.js

@@ -0,0 +1,114 @@
+// lib/connections.js — Git 托管连接（GitHub / GitLab / 华为云 CodeArts 凭据）
+// 全局共享：<dataRoot>/connections.json（与项目无关，一套凭据多项目复用）。
+// token 明文落盘，与本机 GITHUB_TOKEN 环境变量同级安全；UI 注明存储路径。
+import { existsSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { join } from "node:path";
+
+export const CONNECTION_KINDS = {
+  github: { label: "GitHub", defaultHost: "github.com", hostFixed: true, needsUsername: false, tokenLabel: "Access Token" },
+  gitlab: { label: "GitLab", defaultHost: "gitlab.com", hostFixed: false, needsUsername: false, tokenLabel: "Personal Access Token" },
+  codearts: { label: "华为云 CodeArts", defaultHost: "", hostFixed: false, needsUsername: true, tokenLabel: "HTTPS 密码" },
+};
+
+const connFile = (root) => join(root, "connections.json");
+
+export function loadConnections(root) {
+  const file = connFile(root);
+  if (!existsSync(file)) return [];
+  try {
+    const list = JSON.parse(readFileSync(file, "utf8"));
+    return Array.isArray(list) ? list : [];
+  } catch { return []; }
+}
+
+export function saveConnections(root, list) {
+  const tmp = connFile(root) + ".tmp";
+  writeFileSync(tmp, JSON.stringify(list, null, 2));
+  renameSync(tmp, connFile(root));
+}
+
+// 校验 + 规范化；id 直接用 host（同 host 唯一，天然 upsert 键）
+export function normalizeConnection(c, existing = []) {
+  if (!c || typeof c !== "object") throw new Error("连接必须是对象");
+  const kind = CONNECTION_KINDS[c.kind] ? c.kind : null;
+  if (!kind) throw new Error("kind 仅允许 github|gitlab|codearts");
+  const meta = CONNECTION_KINDS[kind];
+  let host = String(c.host || meta.defaultHost || "").trim().toLowerCase();
+  // 去掉用户误粘贴的协议前缀与路径
+  host = host.replace(/^https?:\/\//, "").replace(/\/.*$/, "").replace(/:\d+$/, "");
+  if (!/^[a-z0-9.-]+(\.[a-z0-9-]+)*$/.test(host)) {
+    throw new Error("host 必须是合法域名（如 github.com / gitlab.example.com）");
+  }
+  if (meta.hostFixed && host !== meta.defaultHost) {
+    throw new Error(kind + " 连接的 host 固定为 " + meta.defaultHost);
+  }
+  const token = String(c.token || "").trim();
+  if (!token) throw new Error("token 不能为空");
+  if (meta.needsUsername && !String(c.username || "").trim()) {
+    throw new Error("CodeArts 连接需要 HTTPS 用户名（租户名/IAM用户名，在 CodeArts「个人设置 → HTTPS密码」页获取）");
+  }
+  const dup = existing.find((x) => x.host === host);
+  if (dup && dup.kind !== kind) throw new Error(host + " 已配置为 " + CONNECTION_KINDS[dup.kind].label + " 连接，请先删除原连接");
+  const out = { id: host, kind, host, token, createdAt: dup?.createdAt || new Date().toISOString() };
+  if (meta.needsUsername) out.username = String(c.username).trim();
+  return out;
+}
+
+export function upsertConnection(root, c) {
+  const list = loadConnections(root);
+  const norm = normalizeConnection(c, list);
+  const i = list.findIndex((x) => x.host === norm.host);
+  if (i >= 0) list[i] = norm; else list.push(norm);
+  saveConnections(root, list);
+  return norm;
+}
+
+export function deleteConnection(root, id) {
+  const list = loadConnections(root);
+  const i = list.findIndex((x) => x.id === id || x.host === id);
+  if (i < 0) return null;
+  const [removed] = list.splice(i, 1);
+  saveConnections(root, list);
+  return removed;
+}
+
+// 从仓库/issue URI 解析 hostname：支持 https、ssh://、scp 形态（git@host:path）
+export function hostOf(uri) {
+  const s = String(uri || "").trim();
+  const m = s.match(/^(?:https?|ssh|git):\/\/(?:[^@\/]+@)?([^\/:?#]+)/i);
+  if (m) return m[1].toLowerCase();
+  const scp = s.match(/^git@([^\/:?#]+):/);
+  if (scp) return scp[1].toLowerCase();
+  return null;
+}
+
+export function matchConnection(uri, list) {
+  const host = hostOf(uri);
+  if (!host) return null;
+  return list.find((c) => c.host === host) || null;
+}
+
+// https 仓库地址注入凭据；ssh/scp 形态或已内嵌凭据的地址原样返回（用户显式配置优先）
+export function injectGitCredentials(uri, conn) {
+  const s = String(uri || "");
+  if (!conn || !/^https?:\/\//i.test(s)) return s;
+  try {
+    const u = new URL(s);
+    if (u.username || u.password) return s;
+    if (conn.kind === "github") { u.username = "x-access-token"; u.password = conn.token; }
+    else if (conn.kind === "gitlab") { u.username = "oauth2"; u.password = conn.token; }
+    else { u.username = conn.username || ""; u.password = conn.token; }
+    return u.toString();
+  } catch { return s; }
+}
+
+// 错误信息/事件日志脱敏：https://user:pass@… → https://***@…（URL 可嵌在句子中间，全局替换）
+export function redactUrl(uri) {
+  return String(uri || "").replace(/(https?:\/\/)[^@\/\s'"]+@/gi, "$1***@");
+}
+
+export function maskToken(token) {
+  const t = String(token || "");
+  if (t.length <= 8) return "****";
+  return t.slice(0, 4) + "…" + t.slice(-4);
+}

package/lib/llm.js

@@ -0,0 +1,159 @@
+// lib/llm.js — ctx.llm.stream 封装 + JSON 契约解析（重试一次）
+// makeLlm(ctx, hook, overridesOf)：overridesOf() 返回当前阶段的覆盖配置
+// （provider/model/reasoningEffort/timeoutMs/maxTokens，来自 project.stageConfig），
+// 每次调用时现取，阶段推进/配置修改即时生效。
+const DEFAULT_ROUTE = { provider: "deepseek-official", model: "deepseek-v4-pro" };
+
+// 路由解析 + 来源标注（source：stage=阶段覆盖 / host=宿主默认 / plugin=插件配置 / default=插件兜底）。
+// preflight 端点用它把「当前默认模型从哪来」台面化。
+export function routeInfo(ctx, ov) {
+  // 0) 阶段级覆盖最高优先（配置页按阶段指定模型）
+  if (ov && ov.provider && ov.model) {
+    const route = { provider: ov.provider, model: ov.model };
+    if (ov.reasoningEffort) route.reasoningEffort = ov.reasoningEffort;
+    return { route, source: "stage" };
+  }
+  // 1) 首选宿主 agentDefaultModel 服务（真实生效的默认路由），服务可能不存在，需 try/catch
+  try {
+    const sel = ctx.agentDefaultModel && typeof ctx.agentDefaultModel.currentSelection === "function"
+      ? ctx.agentDefaultModel.currentSelection() : undefined;
+    if (sel && sel.provider && sel.model) {
+      const route = { provider: sel.provider, model: sel.model };
+      if (sel.reasoningEffort) route.reasoningEffort = sel.reasoningEffort; // GenerateOptions 支持该字段
+      return { route, source: "host" };
+    }
+  } catch {}
+  // 2) 次级回退：插件配置 agent-default-model（向后兼容既有测试）
+  try {
+    const cfg = typeof ctx.getConfig === "function" ? ctx.getConfig("agent-default-model") : undefined;
+    if (cfg && cfg.provider && cfg.model) return { route: { provider: cfg.provider, model: cfg.model }, source: "plugin" };
+  } catch {}
+  // 3) 最终兜底
+  return { route: DEFAULT_ROUTE, source: "default" };
+}
+
+function resolveRoute(ctx, ov) {
+  return routeInfo(ctx, ov).route;
+}
+
+export function extractJson(text) {
+  const fenced = String(text).match(/```(?:json)?\s*([\s\S]*?)```/);
+  const candidate = fenced ? fenced[1] : (() => {
+    const s = String(text);
+    const i = s.indexOf("{"), j = s.lastIndexOf("}");
+    if (i === -1 || j <= i) throw new Error("契约解析失败: 输出不含 JSON 对象");
+    return s.slice(i, j + 1);
+  })();
+  try { return JSON.parse(candidate); }
+  catch (e) { throw new Error("契约解析失败: " + e.message); }
+}
+
+export function makeLlm(ctx, hook, overridesOf) {
+  const takeOverrides = () => (typeof overridesOf === "function" ? overridesOf() : null) || {};
+  async function complete({ system, user, maxTokens = 8192, signal } = {}) {
+    const ov = takeOverrides();
+    const route = resolveRoute(ctx, ov);
+    const effMaxTokens = ov.maxTokens > 0 ? Math.floor(ov.maxTokens) : maxTokens;
+    const timeoutMs = ov.timeoutMs > 0 ? ov.timeoutMs : 0;
+    const t0 = Date.now();
+    // 事件预览：prompt 头 + 响应头，截断防膨胀
+    const preview = (s, n) => {
+      const str = String(s == null ? "" : s).replace(/\s+/g, " ").trim();
+      return str.length > n ? str.slice(0, n) + "…" : str;
+    };
+    // 开打即记「调用中」：LLM 单次调用可达分钟级，进行中就要在阶段详情可见
+    hook?.({ kind: "llm", name: route.model + " · 调用中", ms: null, ok: true,
+      detail: `【prompt】${preview(user, 300)}` });
+    // 流式累积包成 Promise，外层与超时 race（宿主 stream 的 signal 中断不可依赖，
+    // 超时直接拒绝，让阶段失败可感知可重试，而不是无限挂起）
+    const streamP = (async () => {
+      let text = "";
+      for await (const chunk of ctx.llm.stream({
+        provider: route.provider, model: route.model,
+        // 路由若带 reasoningEffort 则一并传给 stream（GenerateOptions 支持该字段）
+        ...(route.reasoningEffort ? { reasoningEffort: route.reasoningEffort } : {}),
+        // dsh-llm 的 Message.content 是 ContentBlock[]（types/message.d.ts:126），字符串会触发适配器 content.some 异常
+        system, messages: [{ role: "user", content: [{ type: "text", text: user }] }], maxTokens: effMaxTokens, signal,
+      })) {
+        if (chunk.type === "text-delta") text += chunk.text;
+        if (chunk.type === "finish") {
+          // dsh-llm 的 finish reason 是对象（{kind,failure?}），同时兼容字符串
+          const kind = typeof chunk.reason === "string" ? chunk.reason : chunk.reason?.kind;
+          if (kind === "error" || kind === "aborted") {
+            // failure 可能是对象，取最有信息量的字段；都没有就用 kind
+            const detail = chunk.reason?.failure?.message || chunk.reason?.failure?.code || kind;
+            throw new Error("LLM 调用失败: " + detail);
+          }
+        }
+      }
+      if (!text.trim()) throw new Error("LLM 返回为空");
+      return text;
+    })();
+    let timer = null;
+    const timeoutP = timeoutMs > 0
+      ? new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`LLM 调用超时（${timeoutMs}ms，可在「配置」页调整该阶段的超时时间）`)), timeoutMs);
+      })
+      : null;
+    try {
+      const text = await (timeoutP ? Promise.race([streamP, timeoutP]) : streamP);
+      hook?.({ kind: "llm", name: route.model + " · 完成", ms: Date.now() - t0, ok: true,
+        detail: `prompt ${String(user || "").length} 字 → 响应 ${text.length} 字\n【prompt】${preview(user, 300)}\n——\n【响应】${preview(text, 500)}` });
+      return text;
+    } catch (e) {
+      hook?.({ kind: "llm", name: route.model + " · 失败", ms: Date.now() - t0, ok: false,
+        detail: `prompt ${String(user || "").length} 字\n【prompt】${preview(user, 300)}\n——\n【错误】${String((e && e.message) || e)}` });
+      throw e;
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  // 流式单次调用（悬浮智能助手用）：messages 为简化形态 [{role, text}]，
+  // 内部转 ContentBlock 数组；每个 text-delta 回调 onDelta，返回完整文本。
+  // 路由解析与 finish 错误判定与 complete 一致，但不带超时 race 与事件钩子
+  // （助手调用不属于任何 Run，不写 events.jsonl；中断由调用方 signal 控制）
+  async function streamText({ system, messages = [], maxTokens = 8192, signal, onDelta } = {}) {
+    const route = resolveRoute(ctx, takeOverrides());
+    let text = "";
+    for await (const chunk of ctx.llm.stream({
+      provider: route.provider, model: route.model,
+      ...(route.reasoningEffort ? { reasoningEffort: route.reasoningEffort } : {}),
+      system,
+      messages: messages.map(({ role, text: t }) => ({ role, content: [{ type: "text", text: String(t || "") }] })),
+      maxTokens, signal,
+    })) {
+      if (chunk.type === "text-delta") {
+        text += chunk.text;
+        if (typeof onDelta === "function") onDelta(chunk.text);
+      }
+      if (chunk.type === "finish") {
+        const kind = typeof chunk.reason === "string" ? chunk.reason : chunk.reason?.kind;
+        if (kind === "error" || kind === "aborted") {
+          const detail = chunk.reason?.failure?.message || chunk.reason?.failure?.code || kind;
+          throw new Error("LLM 调用失败: " + detail);
+        }
+      }
+    }
+    if (!text.trim()) throw new Error("LLM 返回为空");
+    return text;
+  }
+
+  async function completeJson({ system, user, required = [], maxTokens, signal } = {}) {
+    let lastErr = null;
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const prompt = attempt === 0 ? user
+        : user + `\n\n【上次输出无法解析：${lastErr}。请只输出一个合法 JSON 对象，不要输出任何其他文字。】`;
+      try {
+        const out = extractJson(await complete({ system, user: prompt, maxTokens, signal }));
+        if (typeof out !== "object" || out === null || Array.isArray(out)) throw new Error("契约解析失败: 输出不是 JSON 对象");
+        const missing = required.filter((k) => !(k in out));
+        if (missing.length) throw new Error("契约解析失败: 缺字段 " + missing.join(","));
+        return out;
+      } catch (e) { lastErr = (e && e.message) || String(e); }
+    }
+    throw new Error(lastErr);
+  }
+
+  return { complete, completeJson, streamText };
+}

package/lib/pipeline.js

@@ -0,0 +1,151 @@
+// lib/pipeline.js — 状态机核心（不含任何 LLM/执行细节）
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { writeArtifact, appendArtifactLine, timestamp } from "./store.js";
+import { STAGE_DEFS, stageDelegated, delegateReady } from "./stageConfig.js";
+
+export const STAGES = [
+  { id: "P1",  name: "IssueAnalyzer",      artifact: "01-issue-analysis.json",     key: false },
+  { id: "P2",  name: "Search Layer",       artifact: "02-search-candidates.json",  key: false },
+  { id: "P3",  name: "Code Understanding", artifact: "03-code-understanding.md",   key: false },
+  { id: "P4",  name: "Hypothesis",         artifact: "04-hypotheses.json",         key: false },
+  { id: "P5",  name: "Planner",            artifact: "05-task-graph.json",         key: true  },
+  { id: "P6",  name: "代码优化",            artifact: "06-implementation/",         key: true  },
+  { id: "P7",  name: "Patch Pipeline",     artifact: "ledger/patch-ledger.jsonl",  key: false },
+  { id: "P8",  name: "TestRunner",         artifact: "07-test-report.json",        key: false },
+  { id: "P9",  name: "Reviewer",           artifact: "08-review-report.json",      key: true  },
+  { id: "P10", name: "FailureClassifier",  artifact: "09-failure-analysis.json",   key: false },
+  { id: "P11", name: "PRBuilder + Eval",   artifact: "10-pr-description.md",       key: true  },
+];
+export const MAIN_FLOW = ["P1", "P2", "P3", "P4", "P5", "P6", "P7", "P8", "P9", "P11"];
+
+export function initRun({ runId, slug, trigger, reviewMode, p6Mode }) {
+  return {
+    id: runId, project: slug, trigger, reviewMode, p6Mode,
+    createdAt: new Date().toISOString(), status: "pending", current: "P1",
+    stages: Object.fromEntries(STAGES.map((s) => [s.id, { status: "pending", attempts: 0 }])),
+  };
+}
+
+const runFile = (runDir) => join(runDir, "run.json");
+export function saveRun(runDir, run) { writeArtifact(runDir, "run.json", JSON.stringify(run, null, 2)); }
+export function loadRun(runDir) {
+  return existsSync(runFile(runDir)) ? JSON.parse(readFileSync(runFile(runDir), "utf8")) : null;
+}
+
+export function isGate(run, stageId) {
+  if (run.reviewMode === "every") return true;
+  if (run.reviewMode === "key-only") return !!STAGES.find((s) => s.id === stageId)?.key;
+  return false;
+}
+
+// session 模式的外部执行就绪判定（与 p7-patch 的 collectPatches 口径一致：
+// coder-report.json 存在，或 patches/ 下有 *.diff）
+export function sessionPatchesReady(runDir) {
+  if (existsSync(join(runDir, "06-implementation", "coder-report.json"))) return true;
+  const dir = join(runDir, "06-implementation", "patches");
+  if (!existsSync(dir)) return false;
+  return readdirSync(dir).some((f) => f.endsWith(".diff"));
+}
+
+function appendSpan(runDir, span) {
+  mkdirSync(join(runDir, "trace"), { recursive: true });
+  appendFileSync(join(runDir, "trace", "spans.jsonl"), JSON.stringify({ at: new Date().toISOString(), ...span }) + "\n");
+}
+
+// 过程事件（trace/events.jsonl，UI 阶段详情展示；写失败不影响主流程）
+function appendEvent(runDir, stage, ev) {
+  try {
+    appendArtifactLine(runDir, "trace/events.jsonl", {
+      at: new Date().toISOString(), stage,
+      kind: ev.kind || "stage", name: String(ev.name || "").slice(0, 200),
+      detail: String(ev.detail == null ? "" : ev.detail).slice(0, 2000),
+      ms: typeof ev.ms === "number" ? Math.round(ev.ms) : null, ok: ev.ok !== false,
+    });
+  } catch { /* 忽略 */ }
+}
+
+export async function advance(rcx) {
+  const { run, runDir, executors } = rcx;
+  // 处于复核门等待时不再推进，避免重复执行门阶段（违反不变式并浪费执行）
+  if (run.status === "awaiting_review") return;
+  // 一次调用持续推进，直到遇上复核门（awaiting_review）或全部通过（completed）；
+  // 阶段失败则立即停在该阶段（failed）。每次状态变化都同步落盘 run.json。
+  for (;;) {
+    // 每个阶段开始前查盘：外部 stop/delete 改写了 run.json 时立即终止推进
+    const disk = loadRun(runDir);
+    if (!disk || disk.status === "stopped" || disk.status === "deleted") { Object.assign(run, disk || { status: "stopped" }); return; }
+    const nextId = MAIN_FLOW.find((id) => run.stages[id].status !== "approved");
+    if (!nextId) { run.status = "completed"; saveRun(runDir, run); return; }
+    const st = run.stages[nextId];
+    run.current = nextId; run.status = "running"; st.status = "running";
+    st.startedAt = new Date().toISOString();
+    saveRun(runDir, run);
+    appendEvent(runDir, nextId, { kind: "stage", name: nextId + " 开始", detail: STAGES.find((s) => s.id === nextId)?.name || "" });
+    const t0 = Date.now();
+    try {
+      const result = await executors[nextId](rcx);
+      // 执行器运行期间可能被外部 stop/delete：落盘前复查，避免把 running 写回覆盖 stopped
+      const diskAfter = loadRun(runDir);
+      if (!diskAfter || diskAfter.status === "stopped" || diskAfter.status === "deleted") {
+        Object.assign(run, diskAfter || { status: "stopped" });
+        return;
+      }
+      st.artifact = result && result.artifact;
+      if (result && result.external) st.external = true; // session 模式：实施移交外部会话
+      st.finishedAt = new Date().toISOString();
+      appendSpan(runDir, { span: nextId, ms: Date.now() - t0, decision: (result && result.summary) || "" });
+      st.status = isGate(run, nextId) ? "awaiting_review" : "approved";
+      run.status = st.status === "approved" ? "running" : "awaiting_review";
+      // external 阶段的实施不在本阶段完成，事件文案不能写"完成"（避免误导为已交付）
+      const doneLabel = result && result.external
+        ? nextId + " 任务包已生成 · 等待外部会话执行"
+        : nextId + (st.status === "awaiting_review" ? " 完成 · 待复核" : " 完成");
+      appendEvent(runDir, nextId, { kind: "stage", name: doneLabel,
+        detail: (result && result.summary) || "", ms: Date.now() - t0 });
+    } catch (e) {
+      st.status = "failed"; st.error = String((e && e.message) || e);
+      run.status = "failed";
+      appendSpan(runDir, { span: nextId, ms: Date.now() - t0, error: st.error });
+      appendEvent(runDir, nextId, { kind: "stage", name: nextId + " 失败", detail: st.error, ms: Date.now() - t0, ok: false });
+      saveRun(runDir, run);
+      return;
+    }
+    saveRun(runDir, run);
+    if (st.status === "awaiting_review") return;
+  }
+}
+
+export function applyReview(rcx, { decision, comment }) {
+  const { run, runDir } = rcx;
+  const id = run.current;
+  const st = run.stages[id];
+  if (!st || st.status !== "awaiting_review") return [false, "当前阶段不在待复核状态"];
+  if (decision === "reject" && !String(comment || "").trim()) return [false, "打回必须填写复核意见"];
+  if (decision !== "approve" && decision !== "reject") return [false, "decision 仅允许 approve|reject"];
+  // 委托模式（P6 session/claude、其余阶段配置页委托开关）：实施在插件外完成。
+  // 空手放行会让下游拿不到产物而必然失败，因此通过前必须看到该阶段产出。
+  // 按 p6Mode/stageConfig 推导（不依赖 st.external 字段）：旧版本创建的 run 也能被拦截。
+  if (decision === "approve" && stageDelegated(rcx, id) && !delegateReady(runDir, id)) {
+    const isP6 = id === "P6";
+    const output = isP6 ? "patches/*.diff 或 coder-report.json" : (STAGE_DEFS[id]?.delegateSpec?.output || "阶段产物");
+    const mode = isP6 ? ((run.p6Mode || "session") + " 模式") : "委托模式";
+    return [false, id + " " + mode + "：外部执行方尚未产出（未检测到 " + output + "）。请先在外部智能体执行任务包，产出落盘后再通过复核门"];
+  }
+  const record = { stage: id, decision, comment: comment || "", at: new Date().toISOString() };
+  writeArtifact(runDir, `reviews/${timestamp()}-${decision}-${id}.json`, JSON.stringify(record, null, 2));
+  appendEvent(runDir, id, { kind: "stage", name: id + (decision === "approve" ? " 复核通过" : " 复核打回"),
+    detail: comment || "无意见" });
+  if (decision === "approve") {
+    st.status = "approved";
+    run.status = "running";
+    rcx.reviewComment = "";
+  } else {
+    st.status = "pending";
+    st.attempts += 1;
+    run.status = "running";
+    rcx.reviewComment = comment;
+  }
+  saveRun(runDir, run);
+  return [true, decision === "approve" ? "已通过" : "已打回，将带意见重跑"];
+}