pi-web-ui 0.94.1 → 0.96.0

package/dist/server/office-parse.js

@@ -0,0 +1,375 @@
+/**
+ * Office 文档纯文本提取（docx / xlsx / xlsm，csv 由调用方按普通文本处理）。
+ *
+ * 给「随处可看」用的：文件预览（files-service readFile）、附件等走 file_content
+ * 下发 Markdown 文本，前端 FilePreview 按 Markdown 渲染表格/段落，无需改协议。
+ *
+ * 零依赖：docx / xlsx 本质是 zip 包，这里用 node:zlib + 手写 zip 中央目录解析
+ * 做最小解包（只支持 stored / deflate，Office 写出的文件都是这两种）。
+ *
+ * 注意：plugins/office-preview/index.mjs 里有一份同逻辑的 JS 拷贝（插件必须
+ * 自包含、不能 import 服务端 TS，见架构文档插件章）。两边改解析时请同步另一份。
+ */
+import { inflateRawSync } from "node:zlib";
+const OFFICE_EXTS = new Set([".docx", ".xlsx", ".xlsm"]);
+/** 单个文件上限（与 office-preview 插件一致）。 */
+export const OFFICE_MAX_FILE_BYTES = 15 * 1024 * 1024;
+/** 解包后总量上限（防 zip 炸弹：小包解出巨量内容）。 */
+export const OFFICE_MAX_UNCOMPRESSED_BYTES = 64 * 1024 * 1024;
+/** 下发文本上限（字符；超出截断并置 truncated）。 */
+export const OFFICE_MAX_TEXT_CHARS = 200_000;
+/** 表格上限：每表行数 × 列数（预览首屏口径）。 */
+const MAX_ROWS = 500;
+const MAX_COLS = 20;
+export function isOfficeFile(name) {
+    const dot = String(name ?? "")
+        .toLowerCase()
+        .lastIndexOf(".");
+    const ext = dot > 0 ? String(name).toLowerCase().slice(dot) : "";
+    return OFFICE_EXTS.has(ext);
+}
+function findEocd(buf) {
+    const sig = 0x06054b50;
+    const minLen = 22;
+    if (buf.length < minLen)
+        throw new Error("不是有效的 zip 文件（太小）");
+    const start = Math.max(0, buf.length - 65536 - minLen);
+    for (let i = buf.length - minLen; i >= start; i--) {
+        if (buf.readUInt32LE(i) === sig)
+            return i;
+    }
+    throw new Error("不是有效的 zip 文件（找不到 EOCD）");
+}
+/** 返回 Map<文件名, Buffer>（只解要的文件，其余跳过）。 */
+export function unzipFiles(buf, wanted) {
+    const want = new Set(wanted);
+    const eocd = findEocd(buf);
+    const cdCount = buf.readUInt16LE(eocd + 10);
+    const cdOffset = buf.readUInt32LE(eocd + 16);
+    const files = new Map();
+    let p = cdOffset;
+    for (let i = 0; i < cdCount; i++) {
+        if (buf.readUInt32LE(p) !== 0x02014b50)
+            throw new Error("zip 中央目录损坏");
+        const flag = buf.readUInt16LE(p + 8);
+        const method = buf.readUInt16LE(p + 10);
+        const compSize = buf.readUInt32LE(p + 20);
+        const uncompSize = buf.readUInt32LE(p + 24);
+        const nameLen = buf.readUInt16LE(p + 28);
+        const extraLen = buf.readUInt16LE(p + 30);
+        const commentLen = buf.readUInt16LE(p + 32);
+        const localOffset = buf.readUInt32LE(p + 42);
+        const name = buf.toString("utf8", p + 46, p + 46 + nameLen);
+        if (want.has(name))
+            files.set(name, { method, compSize, flag, localOffset, uncompSize });
+        p += 46 + nameLen + extraLen + commentLen;
+    }
+    let totalUncomp = 0;
+    const out = new Map();
+    for (const [name, meta] of files) {
+        if (meta.uncompSize > OFFICE_MAX_UNCOMPRESSED_BYTES) {
+            throw new Error("解包后内容过大（疑似 zip 炸弹），拒绝预览");
+        }
+        const lp = meta.localOffset;
+        if (buf.readUInt32LE(lp) !== 0x04034b50)
+            throw new Error(`zip 局部头损坏：${name}`);
+        const lMethod = buf.readUInt16LE(lp + 8);
+        const lNameLen = buf.readUInt16LE(lp + 26);
+        const lExtraLen = buf.readUInt16LE(lp + 28);
+        const dataStart = lp + 30 + lNameLen + lExtraLen;
+        const raw = buf.subarray(dataStart, dataStart + meta.compSize);
+        if (meta.flag & 0x1)
+            throw new Error(`不支持加密 zip 条目：${name}`);
+        const method = lMethod || meta.method;
+        let decompressed;
+        if (method === 0) {
+            decompressed = Buffer.from(raw);
+        }
+        else if (method === 8) {
+            const remainingQuota = OFFICE_MAX_UNCOMPRESSED_BYTES - totalUncomp;
+            if (remainingQuota <= 0)
+                throw new Error("解包后内容过大（疑似 zip 炸弹），拒绝预览");
+            try {
+                decompressed = Buffer.from(inflateRawSync(raw, { maxOutputLength: remainingQuota }));
+            }
+            catch (err) {
+                if (err.message?.includes("maxOutputLength") ||
+                    err.code === "ERR_BUFFER_TOO_LARGE") {
+                    throw new Error("解包后内容过大（疑似 zip 炸弹），拒绝预览");
+                }
+                throw err;
+            }
+        }
+        else {
+            throw new Error(`不支持的压缩方式 ${method}：${name}`);
+        }
+        totalUncomp += decompressed.length;
+        if (totalUncomp > OFFICE_MAX_UNCOMPRESSED_BYTES) {
+            throw new Error("解包后内容过大（疑似 zip 炸弹），拒绝预览");
+        }
+        out.set(name, decompressed);
+    }
+    return out;
+}
+const NAMED_ENTITIES = { lt: "<", gt: ">", amp: "&", quot: '"', apos: "'" };
+/**
+ * 单轮解码命名实体与十/十六进制数字实体（一次扫描同时匹配三类）。
+ *
+ * 旧实现分三段 replace：`&amp;#60;` 会先被命名段解码成 `&#60;`、再被数字段
+ * 解码成 `<`——双重解码让转义文本"逃出"字面量（可注入标签）。单轮扫描把
+ * `&…;` 整体消费、解码产物不参与后续匹配：`&amp;#60;` 正确地得到 `&#60;`。
+ */
+function decodeEntities(s) {
+    return String(s ?? "").replace(/&(?:#([0-9]+);|#x([0-9a-fA-F]+);|([a-zA-Z]+);)/g, (_whole, dec, hex, name) => {
+        if (dec !== undefined) {
+            try {
+                return String.fromCodePoint(Number(dec));
+            }
+            catch {
+                return "";
+            }
+        }
+        if (hex !== undefined) {
+            try {
+                return String.fromCodePoint(Number.parseInt(hex, 16));
+            }
+            catch {
+                return "";
+            }
+        }
+        // 未知的命名实体保留原文（与旧实现一致，不臆造映射）
+        return NAMED_ENTITIES[name ?? ""] ?? _whole;
+    });
+}
+const stripTags = (s) => decodeEntities(String(s ?? "").replace(/<[^>]+>/g, ""));
+/** document.xml 解压后的字节上限：超大 XML 会让段落正则扫描退化成秒级卡顿（同步事件循环被挂死）。 */
+const DOCX_MAX_XML_BYTES = 20 * 1024 * 1024;
+/** docx → 段落数组。 */
+export function parseDocxParagraphs(buf) {
+    const files = unzipFiles(buf, ["word/document.xml"]);
+    const xml = files.get("word/document.xml")?.toString("utf8");
+    if (!xml)
+        throw new Error("docx 里找不到 word/document.xml");
+    // 预检 1：解压后过大的 document.xml 在下面的正则扫描里代价爆炸（一次性物化
+    // 全部段落、非贪婪匹配最坏回溯到文本末尾），直接友好报错而不是挂住进程。
+    if (xml.length > DOCX_MAX_XML_BYTES) {
+        throw new Error(`文档内容过大（document.xml 解压后 ${(xml.length / 1048576).toFixed(1)} MB，上限 20 MB），拒绝预览`);
+    }
+    // 预检 2：正常文档的段落闭合标签与开标签同量级。"只有开标签、没有闭标签"
+    // 的恶意结构会让非贪婪正则在每个候选起点都回溯扫描到文本末尾（O(n²)），
+    // 同步挂死事件循环——开标签远多于闭标签（>2 倍）且闭标签为 0 时直接报错。
+    const opens = xml.match(/<w:p[\s>]/g)?.length ?? 0;
+    const closes = xml.match(/<\/w:p>/g)?.length ?? 0;
+    if (opens > 0 && closes === 0) {
+        throw new Error("文档结构异常（段落标签大量未闭合），疑似恶意文档，拒绝预览");
+    }
+    const paragraphs = [];
+    for (const m of xml.matchAll(/<w:p[\s>][\s\S]*?<\/w:p>/g)) {
+        const pXml = m[0];
+        let text = "";
+        for (const n of pXml.matchAll(/<w:(t|tab|br)[^>]*\/?>([^<]*)(?:<\/w:t>)?/g)) {
+            if (n[1] === "tab")
+                text += "\t";
+            else if (n[1] === "br")
+                text += "\n";
+            else
+                text += decodeEntities(n[2]);
+        }
+        paragraphs.push(text);
+    }
+    while (paragraphs.length > 1 &&
+        paragraphs[paragraphs.length - 1] === "" &&
+        paragraphs[paragraphs.length - 2] === "") {
+        paragraphs.pop();
+    }
+    return paragraphs;
+}
+function colLettersToIndex(letters) {
+    let n = 0;
+    for (const ch of letters.toUpperCase())
+        n = n * 26 + (ch.charCodeAt(0) - 64);
+    return n - 1;
+}
+function splitCellRef(ref) {
+    const m = /^([A-Za-z]+)(\d+)$/.exec(String(ref ?? "").trim());
+    if (!m)
+        return null;
+    return { col: colLettersToIndex(m[1]), row: Number(m[2]) - 1 };
+}
+function parseSharedStrings(xml) {
+    if (!xml)
+        return [];
+    const out = [];
+    for (const m of xml.matchAll(/<si>([\s\S]*?)<\/si>/g)) {
+        const texts = [...m[1].matchAll(/<t[^>]*>([\s\S]*?)<\/t>/g)].map((x) => decodeEntities(x[1]));
+        out.push(texts.join(""));
+    }
+    return out;
+}
+const MAX_PARSE_ROWS = 1000;
+const MAX_PARSE_COLS = 100;
+function parseSheet(xml, shared) {
+    const rows = [];
+    let maxRowSeen = 0;
+    let maxColSeen = 0;
+    for (const m of xml.matchAll(/<row[^>]*>([\s\S]*?)<\/row>/g)) {
+        const rowAttr = m[0].slice(0, m[0].indexOf(">"));
+        const rawRNum = /r="(\d+)"/.exec(rowAttr)?.[1];
+        const rNum = rawRNum ? Number(rawRNum) - 1 : rows.length;
+        if (!Number.isFinite(rNum) || rNum < 0)
+            continue;
+        maxRowSeen = Math.max(maxRowSeen, rNum + 1);
+        // 防 OOM：巨大行号不进行无边界预分配，仅计入总量
+        if (rNum >= MAX_PARSE_ROWS)
+            continue;
+        while (rows.length <= rNum)
+            rows.push([]);
+        const row = rows[rNum];
+        for (const c of m[1].matchAll(/<c\b([^>]*)>([\s\S]*?)<\/c>/g)) {
+            const attrs = c[1];
+            const ref = /r="([^"]+)"/.exec(attrs)?.[1];
+            const t = /t="([^"]+)"/.exec(attrs)?.[1];
+            const pos = splitCellRef(ref ?? "");
+            if (!pos || pos.col < 0)
+                continue;
+            maxColSeen = Math.max(maxColSeen, pos.col + 1);
+            // 防 OOM：巨大列号不进行无边界空字符串 push
+            if (pos.col >= MAX_PARSE_COLS)
+                continue;
+            const inner = c[2];
+            let val = "";
+            if (t === "inlineStr") {
+                val = [...inner.matchAll(/<t[^>]*>([\s\S]*?)<\/t>/g)].map((x) => decodeEntities(x[1])).join("");
+            }
+            else if (t === "s") {
+                const idx = Number(stripTags(/<v>([\s\S]*?)<\/v>/.exec(inner)?.[1] ?? ""));
+                val = Number.isFinite(idx) && shared[idx] !== undefined ? shared[idx] : "";
+            }
+            else if (t === "b") {
+                val = stripTags(/<v>([\s\S]*?)<\/v>/.exec(inner)?.[1] ?? "") === "1" ? "TRUE" : "FALSE";
+            }
+            else {
+                val = stripTags(/<v>([\s\S]*?)<\/v>/.exec(inner)?.[1] ?? "");
+                if (!val)
+                    val = stripTags(inner);
+            }
+            while (row.length <= pos.col)
+                row.push("");
+            row[pos.col] = val;
+        }
+    }
+    return {
+        rows,
+        nRows: Math.max(rows.length, maxRowSeen),
+        nCols: Math.max(Math.max(0, ...rows.map((r) => r.length)), maxColSeen),
+    };
+}
+/** xlsx/xlsm → sheet 数组（名按 workbook 还原，取不到时回落 sheetN）。 */
+export function parseXlsxSheets(buf) {
+    const probe = unzipFiles(buf, ["xl/workbook.xml", "xl/_rels/workbook.xml.rels"]);
+    const wbXml = probe.get("xl/workbook.xml")?.toString("utf8") ?? "";
+    const relsXml = probe.get("xl/_rels/workbook.xml.rels")?.toString("utf8") ?? "";
+    const relTarget = new Map();
+    for (const m of relsXml.matchAll(/<Relationship\b[^>]*>/g)) {
+        const id = /Id="([^"]+)"/.exec(m[0])?.[1];
+        const target = /Target="([^"]+)"/.exec(m[0])?.[1];
+        if (id && target)
+            relTarget.set(id, target.replace(/^\/+/, "").replace(/^xl\//, ""));
+    }
+    const sheetDefs = [];
+    for (const m of wbXml.matchAll(/<sheet\b[^>]*\/>/g)) {
+        const name = /name="([^"]*)"/.exec(m[0])?.[1] ?? `Sheet${sheetDefs.length + 1}`;
+        const rid = /r:id="([^"]+)"/.exec(m[0])?.[1];
+        sheetDefs.push({ name: decodeEntities(name), rid });
+    }
+    let targets = sheetDefs.map((d, i) => {
+        const t = d.rid && relTarget.get(d.rid);
+        return { name: d.name, file: t ? `xl/${t}` : `xl/worksheets/sheet${i + 1}.xml` };
+    });
+    if (targets.length === 0)
+        targets = [{ name: "Sheet1", file: "xl/worksheets/sheet1.xml" }];
+    const files = unzipFiles(buf, ["xl/sharedStrings.xml", ...targets.map((t) => t.file)]);
+    const shared = parseSharedStrings(files.get("xl/sharedStrings.xml")?.toString("utf8"));
+    return targets.map((t) => {
+        const xml = files.get(t.file)?.toString("utf8");
+        const parsed = xml ? parseSheet(xml, shared) : { rows: [], nRows: 0, nCols: 0 };
+        const fullCols = parsed.nCols;
+        const fullRows = parsed.nRows;
+        const nCols = Math.min(MAX_COLS, fullCols);
+        const cut = parsed.rows.slice(0, MAX_ROWS).map((r) => {
+            const row = r.slice(0, MAX_COLS);
+            while (row.length < nCols)
+                row.push("");
+            return row;
+        });
+        return {
+            name: t.name,
+            nRows: fullRows,
+            nCols: fullCols,
+            rows: cut,
+            truncated: fullRows > MAX_ROWS || fullCols > MAX_COLS,
+        };
+    });
+}
+const mdCell = (s) => String(s ?? "")
+    .replace(/\|/g, "\\|")
+    .replace(/\r?\n/g, " ");
+/** 列号 → Excel 式列名（0→A，25→Z，26→AA）。 */
+function colName(i) {
+    let s = "";
+    let n = i;
+    do {
+        s = String.fromCharCode(65 + (n % 26)) + s;
+        n = Math.floor(n / 26) - 1;
+    } while (n >= 0);
+    return s;
+}
+/**
+ * 表头固定用 A/B/C…（与 Excel 列标一致），而不拿第一行数据冒充表头——
+ * 很多表的第一行是通知/标题文字，染成紫色表头又怪又误导。
+ */
+function sheetToMarkdown(sheet) {
+    const head = `## ${sheet.name}（${sheet.nRows} 行 × ${sheet.nCols} 列${sheet.truncated ? "，只看前一部分" : ""}）`;
+    if (sheet.rows.length === 0)
+        return `${head}\n\n（空表）`;
+    const width = Math.max(1, ...sheet.rows.map((r) => r.length));
+    const pad = (r) => {
+        const row = r.slice(0, width);
+        while (row.length < width)
+            row.push("");
+        return row;
+    };
+    const lines = [Array.from({ length: width }, (_, i) => colName(i)), ...sheet.rows.map(pad)].map((r) => `| ${r.map(mdCell).join(" | ")} |`);
+    lines.splice(1, 0, `| ${Array(width).fill("---").join(" | ")} |`);
+    return [head, "", ...lines].join("\n");
+}
+/**
+ * Office 文件 → Markdown 预览文本（前端 FilePreview 按 Markdown 渲染）。
+ * 非 office 扩展名返回 null；zip 损坏/加密等抛错（调用方回落旧的二进制嗅探）。
+ */
+export function extractOfficeText(filename, buf) {
+    const dot = String(filename ?? "")
+        .toLowerCase()
+        .lastIndexOf(".");
+    const ext = dot > 0 ? String(filename).toLowerCase().slice(dot) : "";
+    if (!OFFICE_EXTS.has(ext))
+        return null;
+    if (buf.length > OFFICE_MAX_FILE_BYTES) {
+        throw new Error(`文件太大（${(buf.length / 1048576).toFixed(1)} MB），Office 预览上限 15 MB`);
+    }
+    let text;
+    let truncated = false;
+    if (ext === ".docx") {
+        const paras = parseDocxParagraphs(buf);
+        text = paras.join("\n");
+        truncated = text.length > OFFICE_MAX_TEXT_CHARS;
+    }
+    else {
+        const sheets = parseXlsxSheets(buf);
+        text = sheets.map(sheetToMarkdown).join("\n\n");
+        truncated = text.length > OFFICE_MAX_TEXT_CHARS || sheets.some((s) => s.truncated);
+    }
+    if (text.length > OFFICE_MAX_TEXT_CHARS)
+        text = text.slice(0, OFFICE_MAX_TEXT_CHARS);
+    return { text, truncated };
+}

package/dist/server/patch-tool.js

@@ -0,0 +1,85 @@
+/**
+ * patch-tool.ts — 导出给 AI Agent 的结构化补丁工具（Hashline Patch Tool）。
+ *
+ * 核心设计：
+ * - 解决标准 edit 工具容易因缩进幻觉、空白字符或行号漂移导致编辑失败的问题。
+ * - 补丁语言基于 [path#TAG] 内容哈希锚点，支持精确行替换（PUT N.=M:）、
+ *   语法块级替换（PUT N*:，自动匹配闭合括号/缩进）、行前/后插入（PUT <N: / PUT >N:）、
+ *   剪切与寄存器粘贴（CUT / PUT @reg）、文件删除（REM）与重命名（MV）。
+ * - 当文件被外部改动导致哈希不一致时，自动尝试 3-Way Merge 冲突自愈。
+ */
+import { resolve } from "node:path";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { applyHashlinePatch, computeFileHash, formatHashlineHeader, formatNumberedLines, globalSnapshotStore, } from "./hashline-engine.js";
+import { getLiveLspDiagnostics } from "./lsp-tool.js";
+export const PATCH_TOOL_NAME = "patch";
+export function makePatchTool(options) {
+    const cwd = options.cwd;
+    return defineTool({
+        name: PATCH_TOOL_NAME,
+        label: "Apply Hashline patch",
+        description: `Apply content-hashed, line-anchored patches to workspace files — prevents stale edits, line drift, and indentation hallucination.
+Each file section starts with \`[path#TAG]\` (or \`[path]\` if the hash is unknown yet). Operations:
+- \`PUT N.=M:\` replace lines N..M (inclusive) with the following \`+TEXT\` lines.
+- \`PUT N*:\` replace the whole syntactic block starting at line N (closing brace/indent auto-resolved).
+- \`PUT <N:\` insert before line N (\`<1\` = head of file); \`PUT >N:\` insert after (\`>$\` = end).
+- \`CUT N.=M [@name]\` / \`CUT N* [@name]\` delete lines and save to register; \`PUT <N @name\` / \`PUT >N @name\` paste it.
+- \`REM\` delete file; \`MV dest/path\` move/rename file.
+- Body rows under \`:\` headers MUST start with \`+\` (\`+\` alone = blank line).
+On divergence the engine attempts a 3-way merge. After success the tool returns the next anchor tag and live LSP diagnostics.`,
+        parameters: Type.Object({
+            patch: Type.String({
+                description: "The complete Hashline patch text containing one or more [path#TAG] sections with PUT/CUT/REM/MV operations.",
+            }),
+            timeout: Type.Optional(Type.Number({
+                description: "Optional execution timeout in seconds.",
+            })),
+        }),
+        async execute(_callId, params, _signal, _onUpdate, _ctx) {
+            const patchText = typeof params?.patch === "string" ? params.patch : "";
+            if (!patchText.trim()) {
+                const emptyReport = {
+                    ok: false,
+                    summary: "Empty patch text provided.",
+                    results: [],
+                    error: "Empty patch",
+                };
+                return {
+                    content: [{ type: "text", text: "Error: No patch content provided." }],
+                    details: emptyReport,
+                };
+            }
+            const report = applyHashlinePatch(patchText, {
+                cwd,
+                snapshotStore: globalSnapshotStore,
+            });
+            if (!report.ok) {
+                return {
+                    content: [{ type: "text", text: `Patch Failed:\n${report.summary}` }],
+                    details: report,
+                };
+            }
+            const textOutput = [report.summary];
+            // 为成功修改的文件输出最新的头部标签，方便 Agent 连续进行下一步修改
+            for (const r of report.results) {
+                if (r.op !== "deleted" && r.newHash) {
+                    const targetPath = r.newPath || r.filePath;
+                    textOutput.push(`\nNext edit anchor for ${targetPath}: \`${formatHashlineHeader(targetPath, r.newHash)}\``);
+                    try {
+                        const fullPath = resolve(cwd, targetPath);
+                        const diags = await getLiveLspDiagnostics(fullPath, cwd);
+                        if (diags) {
+                            textOutput.push(`\nLive LSP diagnostics for ${targetPath}:\n${diags}`);
+                        }
+                    }
+                    catch { }
+                }
+            }
+            return {
+                content: [{ type: "text", text: textOutput.join("\n") }],
+                details: report,
+            };
+        },
+    });
+}

package/dist/server/permission-preset.js

@@ -0,0 +1,25 @@
+/**
+ * 权限预设相关辅助逻辑与会话回放。
+ */
+/**
+ * 从会话 sessionManager entries 回放恢复最后设定的权限预设（若从未设定则返回 undefined）。
+ * customType 为 "permission/preset"，载荷结构为 { preset: string }。
+ */
+export function readPermissionFromSession(sm) {
+    try {
+        const mgr = sm;
+        if (typeof mgr?.getEntries !== "function")
+            return undefined;
+        const entries = mgr.getEntries();
+        for (let i = entries.length - 1; i >= 0; i--) {
+            const e = entries[i];
+            if (e?.type === "custom" && e.customType === "permission/preset" && typeof e.data?.preset === "string") {
+                return e.data.preset;
+            }
+        }
+    }
+    catch {
+        // ignore
+    }
+    return undefined;
+}

package/dist/server/plan-manager.js

@@ -0,0 +1,114 @@
+/**
+ * server/plan-manager.ts
+ *
+ * 结构化任务计划看板与步骤状态机（Plan Mode / Step State Machine）。
+ *
+ * 借鉴 DeepSeek Harness (DSH) 的 dsh-plan-mode：
+ * 1. 任务步骤状态机（Step State Machine）：
+ *    - 步骤字段：id, title, status ("pending" | "in_progress" | "done" | "failed"), description
+ *    - 总体进度与当前执行中步骤
+ * 2. 计划管理与更新（PlanManager）：
+ *    - 模型可通过 customTool `plan_update` 更新
+ *    - 客户端也可通过协议消息 `plan_update` 调整
+ *    - 状态自动同步到快照 `UiState.plan`
+ */
+const VALID_STATUSES = new Set(["pending", "in_progress", "done", "failed"]);
+export class PlanManager {
+    plans = new Map();
+    /** 获取指定会话的计划状态。 */
+    getPlan(conversationId) {
+        return this.plans.get(conversationId) ?? null;
+    }
+    /** 设置/全量更新指定会话的计划。 */
+    setPlan(conversationId, steps, activeStepId) {
+        const normalizedSteps = (Array.isArray(steps) ? steps : []).map((s, idx) => {
+            const status = (VALID_STATUSES.has(s.status) ? s.status : "pending");
+            return {
+                id: String(s.id || `step-${idx + 1}`),
+                title: String(s.title || "").slice(0, 200),
+                status,
+                ...(s.description ? { description: String(s.description).slice(0, 1000) } : {}),
+            };
+        });
+        // 自动推断 activeStepId：优先显式传参；否则推断第一个 in_progress 的步骤
+        let effectiveActiveId = activeStepId;
+        if (effectiveActiveId === undefined) {
+            const inProg = normalizedSteps.find((s) => s.status === "in_progress");
+            effectiveActiveId = inProg ? inProg.id : null;
+        }
+        const state = {
+            steps: normalizedSteps,
+            activeStepId: effectiveActiveId,
+            updatedAt: Date.now(),
+        };
+        this.plans.set(conversationId, state);
+        return state;
+    }
+    /** 增量更新单个步骤的状态或内容。 */
+    updateStep(conversationId, stepId, patch) {
+        const current = this.plans.get(conversationId);
+        if (!current)
+            return null;
+        const idx = current.steps.findIndex((s) => s.id === stepId);
+        if (idx === -1)
+            return null;
+        const currentStep = current.steps[idx];
+        const nextStatus = patch.status && VALID_STATUSES.has(patch.status) ? patch.status : currentStep.status;
+        // patch 里剥掉 id：步骤 id 是 activeStepId / first-match 推进的锚点，
+        // 被改掉会让 activeStepId 悬空（指向不存在的步骤）。
+        const { id: _ignored, ...rest } = patch;
+        const nextStep = {
+            ...currentStep,
+            ...rest,
+            status: nextStatus,
+            // title/description 与 setPlan 同口径截断（200/1000），防超长内容撑爆快照。
+            title: String(rest.title ?? currentStep.title ?? "").slice(0, 200),
+        };
+        const description = String(rest.description ?? currentStep.description ?? "").slice(0, 1000);
+        if (description)
+            nextStep.description = description;
+        else
+            delete nextStep.description;
+        const nextSteps = [...current.steps];
+        nextSteps[idx] = nextStep;
+        let nextActive = current.activeStepId;
+        if (patch.status === "in_progress") {
+            nextActive = stepId;
+        }
+        else if (current.activeStepId === stepId && patch.status) {
+            // 当前活动步骤已完成或失败，自动推进到下一个待执行步骤
+            const nextPending = nextSteps.find((s) => s.status === "pending" || s.status === "in_progress");
+            nextActive = nextPending ? nextPending.id : null;
+        }
+        const nextState = {
+            steps: nextSteps,
+            activeStepId: nextActive,
+            updatedAt: Date.now(),
+        };
+        this.plans.set(conversationId, nextState);
+        return nextState;
+    }
+    /** 清除指定会话的计划。 */
+    clearPlan(conversationId) {
+        this.plans.delete(conversationId);
+    }
+    /** 格式化计划为简洁文本，供模型上下文或诊断使用。 */
+    describePlan(conversationId) {
+        const plan = this.getPlan(conversationId);
+        if (!plan || plan.steps.length === 0)
+            return "No active plan.";
+        const doneCount = plan.steps.filter((s) => s.status === "done").length;
+        const total = plan.steps.length;
+        const lines = [`Plan Progress: ${doneCount}/${total} completed`];
+        for (let i = 0; i < plan.steps.length; i++) {
+            const s = plan.steps[i];
+            const icon = s.status === "done" ? "[x]" : s.status === "in_progress" ? "[>]" : s.status === "failed" ? "[!]" : "[ ]";
+            const activeTag = s.id === plan.activeStepId ? " (current)" : "";
+            lines.push(`${icon} ${i + 1}. ${s.title}${activeTag}`);
+            if (s.description) {
+                lines.push(`     ${s.description}`);
+            }
+        }
+        return lines.join("\n");
+    }
+}