@neus117/dsh-anchor 0.0.0-stage → 0.6.0

package/lib/inject.js

@@ -0,0 +1,480 @@
+/**
+ * dsh-anchor — 注入半边：压缩后把锚点塞回上下文。
+ *
+ * 行为：监听 `session/event` 的 `compaction/end` → 往该会话追加一条 `user/message`
+ * （`source.kind = "runtime-context"`，与宿主自己注入的上下文快照同形）→ 内容是锚点原文。
+ * 锚点的「下一步」三行还空着时，额外指路「调 anchor_form 让用户填」。
+ *
+ * 为什么走 session.append 而不是 agent/pre-step：实测 pre-step 返回的 messages 没进会话日志，
+ * 下一轮也看不到（"日志说跑到、屏幕上看不到"）。追加持久化消息是宿主自己注入上下文的同一条路。
+ *
+ * @module dsh-anchor/inject
+ */
+
+import { appendFileSync, copyFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { randomUUID } from "node:crypto";
+
+import { judgmentEmpty, looksLikeEvidence, readText, writeJudgment } from "./core.js";
+
+const TEMPLATE_PATH = join(dirname(fileURLToPath(import.meta.url)), "..", "templates", "anchor.md");
+
+function templateText() {
+  try {
+    return readText(TEMPLATE_PATH);
+  } catch {
+    return "";
+  }
+}
+
+function slugFor(cwd) {
+  const name = basename(String(cwd || "").replace(/[\\/]+$/, ""));
+  if (!name) return "default";
+  const slug = name.replace(/[^\p{L}\p{N}._-]+/gu, "-").replace(/^-+|-+$/g, "");
+  return slug || "default";
+}
+
+/**
+ * 目录推导：`<anchorDir>\<cwd目录名>\<会话短id>-anchor.md`。
+ *
+ * 为什么按会话分（2026-11-06 用户要求"同一个 workspace 里按项目分"）：
+ *   cwd 是会话身上唯一可靠的项目信号，而用户所有会话的 cwd 都是 `D:\Coding\workspace`，
+ *   靠标题/首句猜项目会误判（锚点系统这个会话的首句里就出现过 "DeepDeep"）。
+ *   按会话分是确定性上界：任何会话都不会读到别的项目的锚点；代价是同项目的多个会话不共享锚点。
+ * 没有会话 id 时退回 `<cwd目录名>-anchor.md`（纯函数测试与无会话脚本用得上）。
+ */
+function dirAnchorPath(session, config) {
+  const root = String(config?.["anchorDir"] ?? "").trim()
+    || join(process.env.DSH_HOME || join(homedir(), ".dsh"), "anchors");
+  const cwd = session?.header?.cwd || "";
+  const slug = cwd ? slugFor(cwd) : "default";
+  const short = String(session?.id || "").replace(/^session-/, "").slice(0, 8);
+  const file = short ? join(root, slug, `${short}-anchor.md`) : join(root, `${slug}-anchor.md`);
+  return { file, explicit: false, missingExplicit: false };
+}
+
+/** 锚点定位：显式 anchorFile（存在才用）→ anchorDir + cwd → 默认目录。 */
+export function resolveAnchorPath(session, config) {
+  const explicit = String(config?.["anchorFile"] ?? "").trim();
+  if (explicit && existsSync(explicit)) return { file: explicit, explicit: true, missingExplicit: false };
+  if (explicit) return { ...dirAnchorPath(session, config), explicit: false, missingExplicit: true };
+  return dirAnchorPath(session, config);
+}
+
+/**
+ * 表单侧用同一个解析：按 agent 的会话取 cwd/会话 id，落到和注入完全相同的文件。
+ * 文件不存在时按 createIfMissing 复制模板（这样"第一次用就填"不会因为文件还没被创建而报错）。
+ * 会话拿不到又没有显式 anchorFile 时抛错——不猜路径（测试里也靠这条避免往家目录写东西）。
+ */
+export function anchorTargetFor(ctx, agentId, config, trace = () => {}) {
+  let session;
+  try {
+    session = ctx.get?.("sessions")?.get?.(agentId);
+  } catch {}
+  if (session) return loadAnchor(session, config, trace).file;
+  const explicit = String(config?.["anchorFile"] ?? "").trim();
+  if (!explicit) throw new Error("anchor_form: 拿不到会话且未配置 anchorFile，无法确定锚点路径");
+  return explicit;
+}
+
+export function loadAnchor(session, config, trace) {
+  const maxChars = Number(config?.["maxChars"]) > 0 ? Number(config["maxChars"]) : 6000;
+  const createIfMissing = config?.["createIfMissing"] !== false;
+  const { file, explicit, missingExplicit } = resolveAnchorPath(session, config);
+  if (missingExplicit) trace(`anchorFile 不存在，退回按 cwd 推导：${file}`);
+
+  let created = false;
+  if (!existsSync(file) && createIfMissing) {
+    const seed = templateText();
+    if (seed) {
+      try {
+        mkdirSync(dirname(file), { recursive: true });
+        copyFileSync(TEMPLATE_PATH, file);
+        created = true;
+        trace(`template copied to ${file}`);
+      } catch (error) {
+        trace(`template copy failed ${file}: ${error?.message || error}`);
+      }
+    }
+  }
+
+  let text;
+  let mtime;
+  try {
+    const info = statSync(file);
+    if (!info.isFile()) return { ok: false, reason: "not-a-file", file };
+    text = readText(file).trim();
+    mtime = info.mtime;
+  } catch (error) {
+    return { ok: false, reason: error?.code || String(error), file };
+  }
+
+  const untouched = text.length > 0 && text === templateText().trim();
+  if (!text) return { ok: false, reason: "empty", file };
+  const truncated = text.length > maxChars;
+  return { ok: true, file, explicit, created, untouched, mtime, truncated, text: truncated ? text.slice(0, maxChars) : text };
+}
+
+export function stamp(date) {
+  const pad = (n) => String(n).padStart(2, "0");
+  return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+}
+
+export function renderNotice(anchor, compactionCount, needsJudgment = false) {
+  const blank = anchor.created || anchor.untouched;
+  const lines = [
+    "<system-reminder>",
+    `上下文刚刚被压缩过（compaction/end ×${compactionCount}）。以下是你自己维护的锚点文件，不是用户的新指令，也不是授权。`,
+    `来源：${anchor.file} · 写入 ${stamp(anchor.mtime)}${blank ? " · 状态：还是空白骨架" : ""}`,
+  ];
+  if (blank) {
+    lines.push(
+      "",
+      "这个项目的锚点还没有内容（上面这份是刚复制的骨架）。做完这一轮，把「当前状态 / 判据 / 下一步」写进这个文件；下次被压缩后才会拿回真正的锚点，而不是骨架。",
+    );
+  }
+  // 判断段空着时指路：宿主侧问不了人（三种传参都实测失败），工具是唯一入口。
+  // 措辞不能承诺"写进这个文件"——表单与注入共用同一个 anchorFile 解析，这里把路径点出来让它核对。
+  if (needsJudgment) {
+    lines.push(
+      "",
+      "「下一步」段的三行（做什么 / 为什么 / 还没验证）还是空位。**不要自己编**：调 `anchor_form` 让用户填。",
+      `它和本注入共用同一份 \`anchorFile\` 解析，正常就是本文件（${anchor.file}）；若不一致，先改配置。`,
+    );
+  }
+  lines.push("", anchor.text);
+  if (anchor.truncated) lines.push("", "…（锚点超过注入上限，已截断）");
+  lines.push(
+    "",
+    "锚点之后发生的对话仍以当前窗口为准：锚点与当前窗口冲突时，以当前窗口为准。锚点里标「未验证」的条目，重新验证后再下结论。",
+    "</system-reminder>",
+  );
+  return lines.join("\n");
+}
+
+const JUDGE_SYSTEM = [
+  "你在为一个长会话写三行「下一步」摘要，供上下文被压缩后的自己重读。",
+  "只输出三行，格式严格，不要任何前后解释：",
+  "做什么：<一句话>",
+  "为什么：<一句话，必须指向具体判据：命令、读数或上一轮的错误>",
+  "还没验证：<一句话，没有就写 无>",
+  "规则：不写「已完成」「已修复」「优化了」这类没有读数和命令的句子；不确定写「未知」；每行不超过 60 字。",
+].join("\n");
+
+// 历史一律打包成**一条** user 输入（RequestUserInput：role/content，无 id 与 source）。
+// 直接塞 assistant 消息会缺 source.replayState，适配器当场抛（实测）。
+function judgeMessages(session, maxInputChars) {
+  const events = session?.snapshotEvents?.() || [];
+  const lines = [];
+  let used = 0;
+  for (let i = events.length - 1; i >= 0 && used < maxInputChars; i -= 1) {
+    const ev = events[i];
+    if (ev.type !== "user/message" && ev.type !== "assistant/message") continue;
+    const content = ev.type === "user/message" ? ev.data?.content : ev.data?.message?.content;
+    const text = (Array.isArray(content) ? content : [])
+      .filter((b) => b && (b.type === undefined || b.type === "text"))
+      .map((b) => b.text || "")
+      .join("\n")
+      .trim();
+    if (!text) continue;
+    const slice = text.length > 1200 ? text.slice(0, 1200) : text;
+    used += slice.length;
+    lines.unshift(`[${ev.type === "user/message" ? "用户" : "助手"}] ${slice}`);
+  }
+  if (lines.length < 2) return [];
+  return [{
+    role: "user",
+    content: [{ type: "text", text: `<最近对话>\n${lines.join("\n")}\n</最近对话 >` }],
+  }];
+}
+
+function judgeRoute(session, cfg) {
+  const provider = String(cfg?.provider || "").trim();
+  const model = String(cfg?.model || "").trim();
+  if (provider && model) return { provider, model };
+  const header = session?.requestHeader?.()?.config;
+  if (header?.provider && header?.model) return { provider: header.provider, model: header.model };
+  return null;
+}
+
+function parseJudgment(text) {
+  const out = {};
+  for (const line of String(text || "").split(/\r?\n/)) {
+    const m = /^\s*(做什么|为什么|还没验证)\s*[:：]\s*(.+?)\s*$/.exec(line);
+    if (!m) continue;
+    const value = m[2].slice(0, 200);
+    if (m[1] === "做什么") out.what = value;
+    if (m[1] === "为什么") out.why = value;
+    if (m[1] === "还没验证") out.pending = value;
+  }
+  return out.what && out.why ? out : null;
+}
+
+async function fillJudgment(ctx, session, cfg, trace, file) {
+  const llm = ctx.get?.("llm");
+  if (!llm || typeof llm.stream !== "function") {
+    trace("judge skipped: no llm service");
+    return false;
+  }
+  const route = judgeRoute(session, cfg);
+  if (!route) {
+    trace("judge skipped: no provider/model route");
+    return false;
+  }
+  const messages = judgeMessages(session, Number(cfg?.maxInputChars) > 0 ? Number(cfg.maxInputChars) : 12000);
+  if (messages.length === 0) {
+    trace("judge skipped: too little history");
+    return false;
+  }
+  let text = "";
+  let finish = null;
+  try {
+    const stream = llm.stream({
+      provider: route.provider,
+      model: route.model,
+      system: JUDGE_SYSTEM,
+      messages,
+      maxTokens: Number(cfg?.maxOutputTokens) > 0 ? Number(cfg.maxOutputTokens) : 300,
+      purpose: "compaction",
+      sessionId: session?.id,
+    });
+    for await (const chunk of stream) {
+      if (chunk?.type === "text-delta" && typeof chunk.text === "string") text += chunk.text;
+      if (chunk?.type === "finish") finish = chunk.reason;
+    }
+  } catch (error) {
+    trace(`judge failed: ${error?.message || error}`);
+    return false;
+  }
+  if (!text.trim()) trace(`judge empty output, finish=${JSON.stringify(finish)}`);
+  const judgment = parseJudgment(text);
+  if (!judgment) {
+    trace(`judge unparseable: ${String(text).slice(0, 120).replace(/\n/g, " ")}`);
+    return false;
+  }
+  const written = writeJudgment(file, judgment);
+  trace(`judge filled: what=${judgment.what.slice(0, 40)} wrote=${written.status}`);
+  return written.status === "written";
+}
+
+const ASK_QUESTION = "你在维护一份「锚点」：上下文被压缩后，未来那个你只能看到它。只填三行，别写叙事。";
+const BAD_EXAMPLE = "坏例子：已完成优化 / 已修复 / 继续推进";
+const GOOD_EXAMPLE = "好例子：跑 tools\\bubble-suite.ps1 all 得到 FAIL=1，卡在 close 顺序";
+
+function recentHints(session, limit = 3) {
+  const events = session?.snapshotEvents?.() || [];
+  const users = [];
+  const fails = [];
+  for (let i = events.length - 1; i >= 0 && users.length < limit; i -= 1) {
+    const ev = events[i];
+    if (ev.type === "tool/result" && (ev.data?.message?.isError || ev.data?.isError)) {
+      const text = (ev.data?.message?.content || []).map((b) => b?.text || "").join(" ").trim();
+      if (text && fails.length < 2) fails.push(text.slice(0, 100));
+    }
+    if (ev.type !== "user/message") continue;
+    const text = (ev.data?.content || []).map((b) => b?.text || "").join(" ").trim();
+    if (text) users.push(text.slice(0, 80));
+  }
+  return { users: users.reverse(), fails };
+}
+
+function buildAskQuestions(session) {
+  const { users, fails } = recentHints(session);
+  const context = users.length ? `最近你说过：\n${users.map((u, i) => `${i + 1}. ${u}`).join("\n")}` : "（最近没有用户发言）";
+  const whyOptions = fails.map((f) => ({ label: `上一轮报错：${f}`, description: "直接引用这条作为判据" }));
+  return [
+    { id: "anchor_what", header: "做什么", question: "下一步做什么？（一句话，动词开头）", detail: `${context}\n\n${BAD_EXAMPLE}` },
+    {
+      id: "anchor_why",
+      header: "为什么",
+      question: "为什么这么做？要能指向一条判据（命令 / 数字 / 报错原文 / 用户原话）",
+      detail: `${GOOD_EXAMPLE}\n\n判据缺失的回答=不合格，会被打回重填一次。`,
+      options: whyOptions.length ? whyOptions : undefined,
+    },
+    { id: "anchor_pending", header: "还没验证", question: "哪一条还没验证？没有就写「无」", detail: "交付时必须照抄这一条，所以宁可写「无」也别写没验证的结论。" },
+  ];
+}
+
+/**
+ * `judge.mode = ask`：**宿主侧不可用**——事件回调里拿不到合法的 live agent
+ * （三种传参均实测失败）。保留代码只为把失败路径测清楚；实际入口是工具 anchor_form。
+ */
+async function askJudgment(ctx, session, cfg, trace, file) {
+  const uq = ctx.get?.("userQuestions");
+  const agent = ctx.get?.("agents")?.currentInitiator?.() || ctx.get?.("agents")?.get?.(session?.id);
+  if (!uq || typeof uq.ask !== "function" || !agent) {
+    trace("ask skipped: no userQuestions or live agent");
+    return false;
+  }
+  const timeoutMs = Number(cfg?.askTimeoutMs) > 0 ? Number(cfg.askTimeoutMs) : 600000;
+  const timeout = new Promise((resolve) => setTimeout(() => resolve(null), timeoutMs));
+  const ask = (questions) => Promise.race([uq.ask({ agent: { id: session?.id }, questions }), timeout]);
+  const pick = (answer, id) => {
+    const item = (answer?.answers || []).find((a) => a.id === id);
+    if (!item) return "";
+    const custom = String(item.custom || "").trim();
+    if (custom) return custom;
+    const selected = Array.isArray(item.selected) && item.selected.length ? String(item.selected[0]).trim() : "";
+    return selected;
+  };
+  try {
+    let answer = await ask(buildAskQuestions(session));
+    if (!answer) { trace("ask timed out"); return false; }
+    let what = pick(answer, "anchor_what");
+    let why = pick(answer, "anchor_why");
+    const pending = pick(answer, "anchor_pending");
+    if (why && !looksLikeEvidence(why)) {
+      trace(`ask: why lacks evidence, re-asking (${why.slice(0, 40)})`);
+      answer = await ask([{
+        id: "anchor_why",
+        header: "为什么 · 重填",
+        question: "这条不含判据（命令/数字/报错/原话）。补一条具体依据，或直接写「未知」",
+        detail: `${GOOD_EXAMPLE}\n你刚才写的是：${why}`,
+      }]);
+      const retry = pick(answer, "anchor_why");
+      if (retry) why = retry;
+    }
+    if (!what && !why) { trace("ask: empty answers, skip"); return false; }
+    if (why && !looksLikeEvidence(why) && why !== "未知") why = `${why} [判据缺失]`;
+    const written = writeJudgment(file, { what: what || "未知", why: why || "未知", pending: pending || "无" });
+    trace(`ask filled: what=${String(what).slice(0, 30)} wrote=${written.status}`);
+    return written.status === "written";
+  } catch (error) {
+    trace(`ask failed: ${error?.message || error}`);
+    return false;
+  }
+}
+
+function noticeMessage(text) {
+  return {
+    id: randomUUID(),
+    role: "user",
+    content: [{ type: "text", text }],
+    source: {
+      kind: "runtime-context",
+      form: "snapshot",
+      sections: [{ name: "anchor-recall", text }],
+    },
+  };
+}
+
+/**
+ * 挂钩压缩事件。由 index.js 调用；自己的任何异常都不该传出去。
+ * @param ctx - 宿主上下文
+ * @param config - 整个插件的 config（注入相关字段既可放在 config 顶层，也可放在 config.inject 下）
+ * @param trace - 日志函数
+ */
+export function attachInject(ctx, config, trace) {
+  const feature = config?.inject && typeof config.inject === "object" ? config.inject : {};
+  const onceSession = String(feature?.["onceSession"] ?? config?.["onceSession"] ?? "").trim();
+  let onceArmed = (feature?.["onceOnLoad"] ?? config?.["onceOnLoad"]) === true;
+  const judgeCfg = (feature?.["judge"] ?? config?.["judge"]) ?? {};
+  const judgeEnabled = judgeCfg?.["enabled"] === true;
+  const judgeOnLoad = (feature?.["judgeOnLoad"] ?? config?.["judgeOnLoad"]) === true;
+  const judgeMinInterval = Number(judgeCfg?.["minIntervalMs"]) > 0 ? Number(judgeCfg["minIntervalMs"]) : 1800000;
+  const lastJudge = new Map();
+  const judging = new Set();
+  const pending = new Map();
+  let warned = false;
+
+  trace(`inject: attach anchorFile=${String(config?.["anchorFile"] ?? "") || "(none)"} anchorDir=${String(config?.["anchorDir"] ?? "") || "(default)"} judgeMode=${String(judgeCfg?.["mode"] || "model")} onceOnLoad=${onceArmed}`);
+
+  const warnOnce = (message) => {
+    if (warned) return;
+    warned = true;
+    ctx.logger?.warn?.(`anchor-inject: ${message}`);
+    trace(`warn ${message}`);
+  };
+
+  const inject = (session, compactions) => {
+    const id = session?.id;
+    if (!id) return false;
+    const anchor = loadAnchor(session, config, trace);
+    if (!anchor.ok) {
+      warnOnce(`读不到锚点 ${anchor.file}（${anchor.reason}），本次不注入`);
+      return false;
+    }
+    try {
+      const needsJudgment = judgmentEmpty(anchor.file);
+      session.append("user/message", noticeMessage(renderNotice(anchor, compactions, needsJudgment)), { surfaceOp: "append" });
+      trace(`inject session=${id} file=${anchor.file} chars=${anchor.text.length} compactions=${compactions} blank=${anchor.created || anchor.untouched} needsJudgment=${needsJudgment}`);
+    } catch (error) {
+      warnOnce(`追加消息失败：${error?.message || error}`);
+      return false;
+    }
+    ctx.logger?.info?.(`anchor-inject: 注入 ${anchor.text.length} 字符（${anchor.file}，本会话压缩 ${compactions} 次）`);
+    return anchor.file;
+  };
+
+  const maybeJudge = (session, file) => {
+    if (!judgeEnabled && !judgeOnLoad) return;
+    const id = session?.id;
+    if (!id || judging.has(id)) return;
+    if (!judgmentEmpty(file)) { trace("judge skipped: judgment already filled"); return; }
+    const last = lastJudge.get(id) || 0;
+    if (!judgeOnLoad && Date.now() - last < judgeMinInterval) { trace("judge skipped: interval"); return; }
+    lastJudge.set(id, Date.now());
+    judging.add(id);
+    const mode = String(judgeCfg["mode"] || "model");
+    const runner = mode === "ask"
+      ? askJudgment(ctx, session, judgeCfg, trace, file)
+      : fillJudgment(ctx, session, judgeCfg, trace, file);
+    runner.finally(() => judging.delete(id));
+  };
+
+  ctx.on("session/event", (session, event) => {
+    if (event?.type !== "compaction/end") return;
+    const id = session?.id;
+    if (!id) return;
+    const count = (pending.get(id) || 0) + 1;
+    pending.set(id, count);
+    trace(`compaction/end session=${id} count=${count}`);
+    // 事件分发是 post-commit 的 fire-and-forget 阶段，追加放到下一拍，避免重入。
+    // ask 模式必须在"事件分发链内"同步发起：setTimeout 之后 initiator 就没了（实测）。
+    if (String(judgeCfg["mode"] || "model") === "ask") {
+      const file = inject(session, count);
+      if (file) maybeJudge(session, file);
+      return;
+    }
+    setTimeout(() => {
+      const file = inject(session, count);
+      if (file) maybeJudge(session, file);
+    }, 0);
+  });
+
+  ctx.on("agent/disposed", (payload) => {
+    const id = payload?.agent?.id;
+    if (id) pending.delete(id);
+  });
+
+  if (judgeOnLoad) {
+    setTimeout(() => {
+      try {
+        const session = onceSession ? ctx.get?.("sessions")?.get?.(onceSession) : undefined;
+        if (!session) { trace("judgeOnLoad: session not live"); return; }
+        const anchor = loadAnchor(session, config, trace);
+        if (!anchor.ok) { trace("judgeOnLoad: anchor unreadable"); return; }
+        trace(`judgeOnLoad: ${anchor.file}`);
+        maybeJudge(session, anchor.file);
+      } catch (error) {
+        trace(`judgeOnLoad failed: ${error?.message || error}`);
+      }
+    }, 50);
+  }
+
+  if (onceArmed) {
+    setTimeout(() => {
+      try {
+        const sessions = ctx.get?.("sessions");
+        const session = onceSession ? sessions?.get?.(onceSession) : undefined;
+        trace(`once: session=${session ? session.id : "(not-live)"}`);
+        if (session) inject(session, 0);
+      } catch (error) {
+        trace(`once failed ${error?.message || error}`);
+      }
+      onceArmed = false;
+    }, 0);
+  }
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@neus117/dsh-anchor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.6.0",
+  "description": "Anchor system in one plugin: re-inject your anchor after a context compaction, and let the user fill its three next-step lines from inside the session.",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./core": "./lib/core.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "templates",
+    "cordis.patch.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "dsh": {
+    "manifestVersion": 1,
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web"
+    }
+  },
+  "engines": {
+    "dsh": ">=0.2.0-rc.2 <0.3.0"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "anchor",
+    "compaction",
+    "user-questions"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "test": "node test/run.mjs"
+  }
 }

package/templates/anchor.md

@@ -0,0 +1,26 @@
+# 锚点：<项目> · 更新 <时间>
+
+> 这份文件每轮只改"变了的那几行"。写完自检：每条结论有来源、每条判据能打开。
+
+## 目标
+
+## 约束（用户原话，逐字引用，不改写）
+
+## 当前状态（只写可验证的）
+- 版本/提交：  工作区：
+- 已完成：
+- 未完成：
+
+## 判据（每条结论靠什么成立；给不出判据的标 [推断]）
+- `<命令>` → 期望：… ；产物：`<路径>`
+
+## 已排除（曾以为 → 实测）
+| 曾以为 | 实测 |
+|---|---|
+
+## 下一步（做什么 + 为什么）
+- [待填] 做什么：
+- [待填] 为什么（指到一条判据：命令 / 读数 / 上一轮的错误）：
+- [待填] 还没验证：
+
+## 未验证（交付时必须照抄）