@neus117/dsh-anchor 0.0.0-stage → 0.6.0

package/lib/form.js

@@ -0,0 +1,320 @@
+/**
+ * dsh-anchor — 表单半边：工具 `anchor_form`。
+ *
+ * 三行（做什么 / 为什么 / 还没验证）由人在会话里填，写回**与注入同一份解析出来的**锚点文件；
+ * 第四栏「问我」不写进锚点，原样回到会话，由智能体按问题范围翻历史回答。
+ *
+ * 为什么必须在工具里问人：宿主根插件拿不到合法的 agent 载体（三种传参实测全失败），
+ * 工具执行上下文里的 `exec.agent` 才是。
+ *
+ * @module dsh-anchor/form
+ */
+
+
+import { clip, isProtected, isVagueWhat, looksLikeEvidence, writeJudgment } from "./core.js";
+import { anchorTargetFor } from "./inject.js";
+
+const GOOD_EXAMPLE = "跑 test\\run.mjs 得到 19 passed";
+
+/** 答案取值：自填优先，其次第一个选项，都没有算空。 */
+export function pickAnswer(answer, id) {
+  const item = (answer?.answers || []).find((entry) => entry?.id === id);
+  if (!item) return "";
+  const custom = String(item.custom ?? "").trim();
+  if (custom) return custom;
+  const selected = Array.isArray(item.selected) ? item.selected : [];
+  return String(selected[0] ?? "").trim();
+}
+
+export const DEFAULT_INTRO =
+  "压缩后我看不到这段对话，只能看到这个锚点文件——这三行就是那时的全部依据，所以要写成脱离上下文也能读的样子。";
+
+function blockText(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((block) => (block && (block.type === undefined || block.type === "text") ? block.text || "" : ""))
+    .join(" ")
+    .trim();
+}
+
+/**
+ * 从本会话里取候选：最近两条真实用户原话、最近两条失败调用。顺序新→旧。
+ * 只从末尾往前扫，够数就停（大会话不整份分析）。
+ * 大会话只取尾部若干事件：`snapshotEvents(fromSeq)` 让内存占用有上限，
+ * 否则 5 万事件的会话每次弹表单都要复制整个数组。
+ */
+export function sessionHints(ctx, agent) {
+  const out = { users: [], fails: [], events: 0 };
+  try {
+    const session = ctx.get?.("sessions")?.get?.(agent?.id);
+    if (!session || typeof session.snapshotEvents !== "function") return out;
+    const tail = 400;
+    const seq = Number(session.seq);
+    let events;
+    try {
+      events = Number.isFinite(seq) && seq > tail + 1 ? session.snapshotEvents(seq - tail) : session.snapshotEvents();
+    } catch {
+      events = session.snapshotEvents() || [];
+    }
+    if (!Array.isArray(events)) events = [];
+    out.events = Number.isFinite(seq) ? seq : events.length;
+    for (let i = events.length - 1; i >= 0 && (out.users.length < 2 || out.fails.length < 2); i -= 1) {
+      const event = events[i];
+      if (!event) continue;
+      if (event.type === "tool/result" && out.fails.length < 2) {
+        const failed =
+          event.data?.message?.isError === true || event.data?.isError === true || event.data?.error !== undefined;
+        const text = failed ? blockText(event.data?.message?.content) : "";
+        if (text) out.fails.push(text.replace(/\s+/g, " ").trim().slice(0, 160));
+      } else if (event.type === "user/message" && out.users.length < 2) {
+        // 宿主注入的 system-reminder 也是 user/message，按 source.kind 滤掉
+        if (event.data?.source?.kind !== "user") continue;
+        const text = blockText(event.data?.content);
+        if (text) out.users.push(text.replace(/\s+/g, " ").trim().slice(0, 160));
+      }
+    }
+  } catch {}
+  return out;
+}
+
+const WHAT_LABEL = /^刚才说的第\s*(\d+)\s*条$/;
+const WHY_LABEL = /^上一轮报错\s*(\d+)$/;
+
+/**
+ * 选项 label 只用来"指哪一条"（短，卡片上能整个看到）；真正写进锚点的是被指到的原文。
+ */
+export function resolveChoice(label, hints = {}) {
+  const text = String(label || "").trim();
+  const what = WHAT_LABEL.exec(text);
+  if (what) return hints.users?.[Number(what[1]) - 1] ?? text;
+  const why = WHY_LABEL.exec(text);
+  if (why) return hints.fails?.[Number(why[1]) - 1] ?? text;
+  return text;
+}
+
+/** 表单四题：三个写进锚点的空 + 一个可选提问。hints 用来做可点候选。 */
+export function buildQuestions(hints = {}, options = {}) {
+  const intro = String(options.intro ?? DEFAULT_INTRO).trim();
+  const users = Array.isArray(hints.users) ? hints.users.slice(0, 2) : [];
+  const fails = Array.isArray(hints.fails) ? hints.fails.slice(0, 2) : [];
+  const whatOptions = users.map((text, index) => ({
+    label: `刚才说的第 ${index + 1} 条`,
+    description: `${clip(text, 80)}——选中后写完整原文`,
+  }));
+  const whyOptions = [
+    ...fails.map((text, index) => ({
+      label: `上一轮报错 ${index + 1}`,
+      description: `${clip(text, 80)}——选中后写完整原文`,
+    })),
+    ...users.slice(0, 1).map((text, index) => ({
+      label: `刚才说的第 ${index + 1} 条`,
+      description: `${clip(text, 80)}——用这句当判据，选中后写完整原文`,
+    })),
+  ];
+  return [
+    {
+      id: "anchor_what",
+      header: "做什么",
+      question: "下一步做什么？写成一个能照着做的动作",
+      detail:
+        (intro ? `${intro}\n\n` : "") +
+        "格式：动词 + 对象（改哪个文件 / 跑哪条命令 / 动哪一处）。\n" +
+        "合格：把 anchor_form 挂进 neus 预设的 plugins 并调一次验收\n" +
+        "不合格：继续推进 / 优化一下",
+      ...(whatOptions.length ? { options: whatOptions } : {}),
+    },
+    {
+      id: "anchor_why",
+      header: "为什么",
+      question: "为什么做这一步？给一条能核对的依据",
+      detail:
+        "依据 = 命令、读数、报错原文，或我说过的话。\n" +
+        `合格：${GOOD_EXAMPLE}\n` +
+        "不合格：这样更好 / 上一轮已验收",
+      ...(whyOptions.length ? { options: whyOptions } : {}),
+    },
+    {
+      id: "anchor_pending",
+      header: "还没验证",
+      question: "哪一条还没验证？没有就选「无」",
+      detail: "交付时这句会被原样照抄，所以宁可写「无」，也别写没核过的结论。",
+      options: [{ label: "无", description: "这一轮全部验证过了" }],
+    },
+    {
+      id: "anchor_back",
+      header: "问我",
+      question: "填表时哪里卡住了，或者想让我查点什么？没有就选「没问题」",
+      detail:
+        "写在这里的话会原样回到会话，我按问题的范围去翻聊天记录回答：问细节只看最近几轮，问「当初为什么」会把相关那一段翻出来。这一栏不写进锚点。",
+      options: [{ label: "没问题", description: "跳过，不用额外查询" }],
+    },
+  ];
+}
+
+const NO_QUESTION = /^(没有|没问题|无|不用|跳过|不需要|暂无)[。.!！]?$/;
+
+function renderOutput(_args, value) {
+  const lines = [
+    `锚点已更新：${value.file}`,
+    `做什么：${value.what || "（空）"}`,
+    `为什么：${value.why || "（空）"}`,
+    `还没验证：${value.pending || "（空）"}`,
+  ];
+  if (value.status !== "written") lines.push(`注意：写入状态 ${value.status}${value.detail ? `（${value.detail}）` : ""}`);
+  if (value.question) {
+    lines.push("", `用户提问：${value.question}`);
+    lines.push("先在回复里回答这个问题：按问题范围决定翻多少历史——问细节只看最近几轮，问「当初为什么」把相关那一段翻出来。");
+  }
+  return [{ type: "text", text: lines.join("\n") }];
+}
+
+/**
+ * 注册工具。由 index.js 调用；异常由调用方隔离。
+ * @param ctx - 宿主上下文
+ * @param config - 整个插件的 config
+ * @param trace - 日志函数
+ */
+export function installForm(ctx, config, trace) {
+  const feature = config?.form && typeof config.form === "object" ? config.form : {};
+  const protectedFiles = Array.isArray(config?.["protectedFiles"]) ? config["protectedFiles"] : [];
+  const intro = feature?.["intro"] ?? config?.["intro"];
+
+  const tools = ctx.tools;
+  if (!tools || typeof tools.register !== "function") throw new Error("tools 服务不可用");
+  trace("form: tools 服务就绪");
+
+  const ask = (questions, exec) => ctx.userQuestions.ask({ agent: exec.agent, questions, signal: exec.signal });
+
+  tools.register({
+    name: "anchor_form",    description:
+      "Open a form for the user: 做什么 / 为什么 / 还没验证 (written into the anchor file's 下一步 section) plus an optional question back to you. After the call, answer any question the user asked — read as much session history as that question needs.",
+    parameters: { type: "object", additionalProperties: false, properties: {} },
+    output: {
+      schema: {
+        type: "object",
+        additionalProperties: false,
+        required: ["file", "status"],
+        properties: {
+          file: { type: "string" },
+          status: { type: "string", enum: ["written", "no-change"] },
+          what: { type: "string" },
+          why: { type: "string" },
+          pending: { type: "string" },
+          question: { type: "string" },
+          sessionEvents: { type: "number" },
+          detail: { type: "string" },
+        },
+      },
+      render: renderOutput,
+    },
+    async execute(_args, exec) {
+      if (exec?.agent === undefined) throw new Error("anchor_form: 没有活的 agent 载体，无法问人");
+      // 和注入共用同一份解析（anchorFile → anchorDir/<cwd>/<会话短id>-anchor.md）。
+      // 文件不存在时它按 createIfMissing 复制模板，所以"某会话第一次填"也能直接用。
+      const anchorFile = anchorTargetFor(ctx, exec.agent.id, config, trace);
+      if (isProtected(anchorFile, protectedFiles)) {
+        throw new Error(`anchor_form: ${anchorFile} 在 protectedFiles 里，拒绝写入`);
+      }
+
+      const hints = sessionHints(ctx, exec.agent);
+      trace(`form: ask callId=${exec.callId} agent=${exec.agent?.id} file=${anchorFile} hints=${hints.users.length}u/${hints.fails.length}f/${hints.events}e`);
+
+      let answer;
+      try {
+        answer = await ask(buildQuestions(hints, { intro }), exec);
+      } catch (error) {
+        trace(`form: ask failed: ${error?.code || ""} ${error?.message || error}`);
+        throw error;
+      }
+
+      let what = resolveChoice(pickAnswer(answer, "anchor_what"), hints);
+      let why = resolveChoice(pickAnswer(answer, "anchor_why"), hints);
+      const pending = pickAnswer(answer, "anchor_pending");
+      const rawQuestion = pickAnswer(answer, "anchor_back");
+      const question = NO_QUESTION.test(rawQuestion.trim()) ? "" : rawQuestion;
+
+      if (isVagueWhat(what)) {
+        trace(`form: what too vague, re-asking: ${what}`);
+        try {
+          const retryAnswer = await ask([
+            {
+              id: "anchor_what_retry",
+              header: "做什么 · 打回",
+              question: `「${clip(what, 24)}」不算动作：没有对象，换个人不知道要动哪里。改成「动词 + 对象」再填一次。`,
+              detail:
+                "打回理由：只写了通用动词，压缩后的我看完仍不知道下一步动哪里。\n" +
+                "格式：动词 + 对象（改哪个文件 / 跑哪条命令 / 动哪一处）。\n" +
+                "合格例子：把 anchor_form 挂进 neus 预设的 plugins 并调一次验收",
+            },
+          ], exec);
+          const retry = resolveChoice(pickAnswer(retryAnswer, "anchor_what_retry"), hints);
+          trace(`form: what retry=${JSON.stringify(retry).slice(0, 60)}`);
+          if (retry && !isVagueWhat(retry)) what = retry;
+        } catch (error) {
+          trace(`form: what retry failed: ${error?.message || error}`);
+        }
+      }
+
+      if (why && why !== "未知" && !looksLikeEvidence(why)) {
+        trace(`form: why lacks evidence, re-asking: ${why}`);
+        try {
+          const retryAnswer = await ask([
+            {
+              id: "anchor_why_retry",
+              header: "为什么 · 打回",
+              question: `「${clip(why, 24)}」里没有可核对的依据。补一条命令 / 数字 / 报错原文，或直接写「未知」。`,
+              detail: `打回理由：这条没有判据，压缩后的我没法重跑核对。\n合格例子：${GOOD_EXAMPLE}`,
+            },
+          ], exec);
+          const retry = resolveChoice(pickAnswer(retryAnswer, "anchor_why_retry"), hints);
+          trace(`form: why retry=${JSON.stringify(retry).slice(0, 60)}`);
+          if (retry) why = retry;
+        } catch (error) {
+          trace(`form: why retry failed: ${error?.message || error}`);
+        }
+      }
+      if (why && why !== "未知" && !looksLikeEvidence(why)) why = `${why} [判据缺失]`;
+
+      trace(`form: answer what=${JSON.stringify(what).slice(0, 60)} why=${JSON.stringify(why).slice(0, 60)} pending=${JSON.stringify(pending).slice(0, 40)} question=${JSON.stringify(question).slice(0, 60)}`);
+
+      if (!what && !why) {
+        trace("form: skip 三行都空");
+        return {
+          file: anchorFile,
+          status: "no-change",
+          what: "",
+          why: "",
+          pending: "",
+          question,
+          sessionEvents: hints.events,
+          detail: "用户跳过了三行（没有作答）",
+        };
+      }
+
+      const judgment = { what: what || "未知", why: why || "未知", pending: pending || "无" };
+      const written = writeJudgment(anchorFile, judgment);
+      trace(`form: write status=${written.status} ${written.detail}`);
+      if (written.status === "failed") throw new Error(`anchor_form: ${written.detail}`);
+      return {
+        file: anchorFile,
+        status: written.status === "written" ? "written" : "no-change",
+        what: judgment.what,
+        why: judgment.why,
+        pending: judgment.pending,
+        question,
+        sessionEvents: hints.events,
+        detail: written.detail,
+      };
+    },
+  });
+  trace("form: anchor_form 已注册");
+  // register 没抛 ≠ 工具真的取得到：output.schema 的方言变了会被挡在注册里（我们已经踩过一次
+  // `required` 必须写成数组）。读回来一次，把"静默没挂上"变成一个可查的信号。
+  try {
+    const registered = tools.get?.("anchor_form");
+    trace(`form: verify=${registered ? "ok" : "missing"}`);
+  } catch (error) {
+    trace(`form: verify failed: ${error?.message || error}`);
+  }
+}

package/lib/index.js

@@ -0,0 +1,86 @@
+/**
+ * dsh-anchor — 锚点系统的唯一插件。
+ *
+ * 两个半边，同一个锚点文件：
+ *   注入（inject）：会话出现 `compaction/end` 时，把锚点原文追加回上下文；
+ *                   「下一步」三行还空着时，指路让智能体调 `anchor_form`。
+ *   表单（form）：  工具 `anchor_form` 让**人在会话里**填三行，写回**同一份解析出来的**文件。
+ *
+ * 为什么合成一个包（2026-11-06）：
+ *   两个包各有一份 `writeJudgment`，`$&` 那个写盘 bug 只长在其中一份里；而且两份 `anchorFile`
+ *   配置可以指向不同文件——"人填的"喂不到"压缩后读取的"。合并后写盘规则、路径解析、三行文案
+ *   都只有一份，配置也只有一份。
+ *
+ * 挂载纪律：
+ *   两半各自 try/catch 隔离——任何一边挂不上，另一边照常工作，宿主也不会被拖下水
+ *   （预设里整棵树会因为一行 fiber 抛错而挂载失败，见 2026-11-06 事故记录）。
+ *
+ * @module dsh-anchor
+ */
+
+import { appendFileSync, statSync, truncateSync } from "node:fs";
+
+import { attachInject } from "./inject.js";
+import { installForm } from "./form.js";
+
+const TRACE_MAX_BYTES = 256 * 1024;
+
+export const name = "dsh-anchor";
+// ctx.tools / ctx.userQuestions / ctx.sessions 都需要声明 inject 才可读。
+export const inject = ["tools", "userQuestions", "sessions"];
+
+export function apply(ctx, config = {}) {
+  try {
+    mount(ctx, config);
+  } catch (error) {
+    try {
+      ctx?.logger?.warn?.(`dsh-anchor: 未挂载（${error?.message || error}）`);
+    } catch {}
+  }
+}
+
+function mount(ctx, config) {
+  const traceFile = String(config?.["traceFile"] ?? "").trim();
+  // 探针文件会随每次压缩/每次表单调用增长；超过 256 KB 就在 apply 时清空。
+  // 只留"最近这一段"够排查了，不设上限等于留了个只会长大的文件。
+  if (traceFile) {
+    try {
+      if (statSync(traceFile).size > TRACE_MAX_BYTES) truncateSync(traceFile, 0);
+    } catch {}
+  }
+  const trace = (line) => {
+    if (!traceFile) return;
+    try {
+      appendFileSync(traceFile, `${new Date().toISOString()} ${line}\n`, "utf8");
+    } catch {}
+  };
+
+  const featureOf = (key) => (config?.[key] && typeof config[key] === "object" ? config[key] : {});
+  const injectEnabled = featureOf("inject").enabled !== false;
+  const formEnabled = featureOf("form").enabled !== false;
+
+  trace(`apply anchorFile=${String(config?.["anchorFile"] ?? "") || "(none)"} inject=${injectEnabled} form=${formEnabled}`);
+
+  if (injectEnabled) {
+    try {
+      attachInject(ctx, config, trace);
+    } catch (error) {
+      trace(`inject failed: ${error?.message || error}`);
+      try { ctx?.logger?.warn?.(`dsh-anchor: 注入半边未挂载（${error?.message || error}）`); } catch {}
+    }
+  }
+
+  if (formEnabled) {
+    try {
+      installForm(ctx, config, trace);
+    } catch (error) {
+      trace(`form failed: ${error?.message || error}`);
+      try { ctx?.logger?.warn?.(`dsh-anchor: 表单半边未挂载（${error?.message || error}）`); } catch {}
+    }
+  }
+}
+
+// 单测与外部脚本用：核心规则只此一份
+export { clip, isProtected, isVagueWhat, judgmentEmpty, looksLikeEvidence, readText, writeJudgment } from "./core.js";
+export { anchorTargetFor, loadAnchor, renderNotice, resolveAnchorPath } from "./inject.js";
+export { buildQuestions, pickAnswer, resolveChoice, sessionHints } from "./form.js";