pi-web-ui 0.63.1 → 0.63.3

package/dist/server/index.js

@@ -604,6 +604,12 @@ wss.on("connection", (ws) => {
             case "delete_session":
                 void cs.deleteSession(msg.path);
                 break;
+            case "rename_session":
+                void cs.renameSession(msg.path, msg.name);
+                break;
+            case "rename_conversation":
+                void cs.renameConversation(msg.id, msg.name);
+                break;
             case "dismiss_conversation":
                 void cs.dismissConversation(msg.id);
                 break;
@@ -724,6 +730,9 @@ wss.on("connection", (ws) => {
             case "terminal_kill":
                 cs.getTerminalManager(msg.conversationId)?.kill(msg.terminalId);
                 break;
+            case "rename_terminal":
+                cs.getTerminalManager(msg.conversationId)?.rename(msg.terminalId, msg.title);
+                break;
             case "run_command":
                 cs.getTerminalManager(msg.conversationId)?.runCommand(msg.terminalId, msg.command, msg.cols, msg.rows, cs.getTerminalCwd(msg.conversationId));
                 break;
@@ -778,6 +787,8 @@ wss.on("connection", (ws) => {
                     visionBridgePrompt: msg.visionBridgePrompt,
                     reviewPrompt: msg.reviewPrompt,
                     reviewDisabledSkills: msg.reviewDisabledSkills,
+                    markersEnabled: msg.markersEnabled,
+                    disabledMarkers: msg.disabledMarkers,
                 });
                 break;
             case "extensions_reload":

package/dist/server/marker-service.js

@@ -0,0 +1,270 @@
+/**
+ * marker-service.ts — 标记服务（内置版 pi-marker-tools）。
+ */
+import { ensureMarkersRegistered, parseMarkers, getMarker, allMarkers, collectGuidance, listMarkerNames, } from "./markers/index.js";
+import { loadStateFromBranch, appendSnapshot } from "./markers/store.js";
+import { TODO_NAMESPACE, initTodoState, describeTodos } from "./markers/builtins/todo.js";
+import { SVC_NAMESPACE, initServiceState, describeServices } from "./markers/builtins/services.js";
+ensureMarkersRegistered();
+const DEFAULT_MARKERS = {
+    markersEnabled: true,
+    disabledMarkers: [],
+};
+export class MarkerService {
+    host;
+    settings;
+    memStore = new Map();
+    overlayCache = new Map();
+    constructor(host) {
+        this.host = host;
+        this.settings = this.host.stateStore.getMarkerSettings(this.host.clientId);
+    }
+    get current() {
+        return { ...this.settings, disabledMarkers: [...this.settings.disabledMarkers] };
+    }
+    get allMarkerNames() {
+        return listMarkerNames();
+    }
+    isGlobalEnabled() {
+        return this.settings.markersEnabled;
+    }
+    isMarkerEnabled(name) {
+        if (!this.settings.markersEnabled)
+            return false;
+        if ((name === "rename" || name === "title") && this.settings.disabledMarkers.includes("conv"))
+            return false;
+        if (name === "conv" && (this.settings.disabledMarkers.includes("rename") || this.settings.disabledMarkers.includes("title")))
+            return false;
+        return !this.settings.disabledMarkers.includes(name);
+    }
+    buildGuidance() {
+        if (!this.settings.markersEnabled)
+            return "";
+        const disabled = new Set(this.settings.disabledMarkers);
+        const lines = collectGuidance(disabled);
+        if (lines.length === 0)
+            return "";
+        return ("\n\n────────── 内联标记工具（重要）──────────\n" +
+            "状态类操作（任务、标记位、通知）请直接写在回答正文里，采用内联标记语法，而不要调用对应工具。\n" +
+            "插件会替你执行并把标记从展示文本中移除，不会中断你的回答。\n\n" +
+            lines.join("\n") +
+            "\n──────────\n");
+    }
+    setEnabled(enabled) {
+        this.settings.markersEnabled = !!enabled;
+        this.host.stateStore.saveMarkerSettings(this.host.clientId, this.settings);
+    }
+    toggleMarker(name, enabled) {
+        const set = new Set(this.settings.disabledMarkers);
+        const group = name === "conv" || name === "rename" || name === "title" ? ["conv", "rename", "title"] : [name];
+        for (const n of group) {
+            if (enabled)
+                set.delete(n);
+            else
+                set.add(n);
+        }
+        this.settings.disabledMarkers = [...set];
+        this.host.stateStore.saveMarkerSettings(this.host.clientId, this.settings);
+    }
+    setAll(settings) {
+        if (settings.markersEnabled !== undefined)
+            this.settings.markersEnabled = !!settings.markersEnabled;
+        if (settings.disabledMarkers !== undefined) {
+            // 归一化 rename 别名：若 conv 被禁用则同步禁用别名
+            const s = new Set(settings.disabledMarkers);
+            if (s.has("conv") || s.has("rename") || s.has("title")) {
+                s.add("conv");
+                s.add("rename");
+                s.add("title");
+            }
+            this.settings.disabledMarkers = [...s];
+        }
+        else {
+            this.host.stateStore.saveMarkerSettings(this.host.clientId, this.settings);
+            return;
+        }
+        this.host.stateStore.saveMarkerSettings(this.host.clientId, this.settings);
+    }
+    // -- state helpers --
+    memFor(convId, ns) {
+        return this.memStore.get(convId)?.get(ns);
+    }
+    setMem(convId, ns, state) {
+        let m = this.memStore.get(convId);
+        if (!m) {
+            m = new Map();
+            this.memStore.set(convId, m);
+        }
+        m.set(ns, state);
+    }
+    getState(convId, namespace, init) {
+        const mgr = this.host.getSessionManager(convId);
+        if (mgr?.getBranch) {
+            try {
+                const branch = mgr.getBranch();
+                const fromBranch = loadStateFromBranch(branch, namespace);
+                if (fromBranch !== undefined) {
+                    this.setMem(convId, namespace, fromBranch);
+                    return structuredClone(fromBranch);
+                }
+            }
+            catch { }
+        }
+        const mem = this.memFor(convId, namespace);
+        if (mem !== undefined)
+            return structuredClone(mem);
+        return init();
+    }
+    saveState(convId, namespace, state) {
+        this.setMem(convId, namespace, structuredClone(state));
+        const mgr = this.host.getSessionManager(convId);
+        appendSnapshot(mgr, namespace, state);
+    }
+    // -- parse & execute --
+    async handleAssistantText(conversationId, text) {
+        if (!text || !this.settings.markersEnabled)
+            return;
+        const tokens = parseMarkers(text);
+        if (tokens.length === 0)
+            return;
+        const disabled = new Set(this.settings.disabledMarkers);
+        const states = new Map();
+        const getOrInit = (ns) => {
+            let st = states.get(ns);
+            if (st !== undefined)
+                return st;
+            if (ns === TODO_NAMESPACE)
+                st = this.getState(conversationId, ns, initTodoState);
+            else if (ns === SVC_NAMESPACE)
+                st = this.getState(conversationId, ns, initServiceState);
+            else {
+                const marker = getMarker(ns);
+                st = marker?.init ? marker.init() : {};
+            }
+            states.set(ns, st);
+            return st;
+        };
+        const dirty = new Set();
+        for (const token of tokens) {
+            if (disabled.has(token.tool))
+                continue;
+            const marker = getMarker(token.tool);
+            if (!marker)
+                continue;
+            const state = getOrInit(token.tool);
+            const ctx = {
+                conversationId,
+                notify: (msg, level) => {
+                    this.host.emit({ type: "notice", level: level ?? "info", text: msg });
+                },
+                renameConversation: (title) => {
+                    this.host.renameConversation(conversationId, title);
+                },
+            };
+            let result;
+            try {
+                result = await marker.apply(token, ctx, state);
+            }
+            catch (e) {
+                result = { applied: false, error: `执行异常: ${e?.message ?? String(e)}` };
+            }
+            if (result.applied) {
+                if (token.tool !== "notify" && token.tool !== "conv" && token.tool !== "rename" && token.tool !== "title") {
+                    dirty.add(token.tool);
+                }
+                else if (token.tool === "conv" || token.tool === "rename" || token.tool === "title") {
+                    // rename 不落库，已直接重命名
+                }
+                else if (token.tool === "notify") {
+                    // 通知不落库
+                }
+                if (token.tool === "todo" || token.tool === "svc")
+                    dirty.add(token.tool);
+            }
+            else if (result.error) {
+                this.host.emit({ type: "notice", level: "warning", text: `[${token.tool}] ${result.error}` });
+            }
+        }
+        for (const ns of dirty) {
+            const mutated = states.get(ns);
+            if (mutated !== undefined)
+                this.saveState(conversationId, ns, mutated);
+        }
+        this.pushOverlay(conversationId);
+    }
+    pushOverlay(conversationId) {
+        const lines = [];
+        for (const m of allMarkers()) {
+            if (this.settings.disabledMarkers.includes(m.name))
+                continue;
+            if (!m.overlay)
+                continue;
+            let state;
+            if (m.name === TODO_NAMESPACE)
+                state = this.getState(conversationId, m.name, initTodoState);
+            else if (m.name === SVC_NAMESPACE)
+                state = this.getState(conversationId, m.name, initServiceState);
+            else {
+                state = this.getState(conversationId, m.name, () => m.init?.() ?? {});
+                if (state === undefined)
+                    continue;
+            }
+            const ctx = {
+                conversationId,
+                notify: () => { },
+                renameConversation: (t) => this.host.renameConversation(conversationId, t),
+            };
+            const ov = m.overlay(state, ctx);
+            if (!ov)
+                continue;
+            lines.push(`[${ov.tool}]`);
+            lines.push(...ov.lines.map((l) => `  ${l}`));
+        }
+        const key = `markers:${conversationId}`;
+        const prev = this.overlayCache.get(key);
+        const next = lines.length ? lines : [];
+        if (prev && prev.join("\n") === next.join("\n"))
+            return;
+        this.overlayCache.set(key, next);
+        if (lines.length > 0) {
+            this.host.emit({ type: "widgets", widgets: [{ key: "markers", lines }] });
+        }
+        else {
+            this.host.emit({ type: "widgets", widgets: [] });
+        }
+    }
+    describe(conversationId, tool, includeDeleted = false) {
+        if (tool === "svc") {
+            const st = this.getState(conversationId, SVC_NAMESPACE, initServiceState);
+            return describeServices(st);
+        }
+        const st = this.getState(conversationId, TODO_NAMESPACE, initTodoState);
+        const visible = st.tasks.filter((t) => includeDeleted || t.status !== "deleted");
+        if (visible.length === 0)
+            return "No todos";
+        return visible.map((t) => `[${t.status}] #${t.id}: ${t.subject}`).join("\n");
+    }
+    getRawState(conversationId, namespace) {
+        if (namespace === TODO_NAMESPACE)
+            return this.getState(conversationId, namespace, initTodoState);
+        if (namespace === SVC_NAMESPACE)
+            return this.getState(conversationId, namespace, initServiceState);
+        const m = getMarker(namespace);
+        return this.getState(conversationId, namespace, () => m?.init?.() ?? {});
+    }
+    /** 供设置面板展示的 marker 目录（含启用状态）。 */
+    /** UI 过滤：rename/title 是 conv 的别名，不单独展示。 */
+    listForUi() {
+        const seen = new Set();
+        const out = [];
+        for (const m of allMarkers()) {
+            if (m.name === "rename" || m.name === "title")
+                continue;
+            if (seen.has(m.name))
+                continue;
+            seen.add(m.name);
+            out.push({ name: m.name, enabled: this.isMarkerEnabled(m.name), guidance: m.guidance });
+        }
+        return out;
+    }
+}

package/dist/server/markers/builtins/notify.js

@@ -0,0 +1,20 @@
+/**
+ * builtins/notify.ts — 纯提醒标记。
+ */
+export const notifyMarker = {
+    name: "notify",
+    guidance: [
+        "- [[notify:<级别>:<内容>]] 仅向用户显示一个非打断性提醒，不会进入正文。级别为 info|warning|success|error。",
+    ],
+    async apply(token, ctx) {
+        const level = token.op || token.kwargs["level"] || "info";
+        const text = token.kwargs["text"] || token.args.join(" ") || "";
+        if (!text)
+            return { applied: false, error: "notify 需要内容" };
+        const safe = (level === "warning" || level === "error" ? level : "info");
+        ctx.notify(text, safe);
+        return { applied: true, feedback: "notified" };
+    },
+    overlay: undefined,
+    init: () => undefined,
+};

package/dist/server/markers/builtins/rename.js

@@ -0,0 +1,102 @@
+/**
+ * builtins/rename.ts — 重命名当前对话标记。
+ *
+ * 需求：加个重命名当前对话 marker。
+ *
+ * 语法：
+ *   [[conv:rename:<新标题>]]        重命名当前对话
+ *   [[rename:set:<新标题>]]         同上（兼容别名）
+ *   [[title:rename:<新标题>]]       同上
+ *   [[rename:new:<新标题>]]         同上
+ *
+ * 兼容：rename 前缀的任意 op 都会被视为重命名，例如 [[rename:set:My Chat]]、
+ *       [[rename:to:My Chat]]。标题来自 args[0] + kwargs[text/name/title] 的
+ *       拼接，未提供则报错。
+ *
+ * 持久化：通过宿主回调直接改对话标题（内存 + 磁盘 transcript session_info），
+ *         不需要额外状态。
+ */
+export const RENAME_NAMESPACE = "conv";
+function extractTitle(token) {
+    // args[0] 是主标题；kwargs 兼容 text/name/title
+    const fromArgs = token.args.join(" ").trim();
+    const fromKw = (token.kwargs["text"] ?? token.kwargs["name"] ?? token.kwargs["title"] ?? "").trim();
+    if (fromArgs && fromKw)
+        return `${fromArgs} ${fromKw}`.trim();
+    return fromArgs || fromKw;
+}
+export const renameMarker = {
+    name: "conv",
+    guidance: [
+        "- 重命名当前对话：[[conv:rename:<新标题>]]（或 [[rename:set:<标题>]]）。标题尽量简短、能概括本次任务。",
+    ],
+    async apply(token, ctx) {
+        if (token.op !== "rename") {
+            return { applied: false, error: `conv 未知操作: ${token.op}（当前仅支持 conv:rename）` };
+        }
+        const title = extractTitle(token);
+        if (!title)
+            return { applied: false, error: "conv:rename 需要一个标题参数 [[conv:rename:<新标题>]]" };
+        if (title.length > 80)
+            return { applied: false, error: "标题过长（最多 80 字）" };
+        if (!ctx.renameConversation)
+            return { applied: false, error: "当前环境不支持重命名" };
+        try {
+            ctx.renameConversation(title);
+            ctx.notify(`已重命名为：${title}`, "info");
+            return { applied: true, feedback: `renamed to "${title}"` };
+        }
+        catch (e) {
+            return { applied: false, error: `重命名失败: ${e.message ?? String(e)}` };
+        }
+    },
+    overlay: undefined,
+    init: () => undefined,
+};
+/** 别名：[[rename:set:标题]] 等同 [[conv:rename:标题]]，方便模型直觉书写。 */
+export const renameAliasMarker = {
+    name: "rename",
+    guidance: [
+        "- [[rename:set:<新标题>]] 同 [[conv:rename:<新标题>]]：重命名当前对话。",
+    ],
+    async apply(token, ctx) {
+        // 兼容任意 op：只要能取到标题就重命名
+        const title = extractTitle(token) || token.op?.trim() || "";
+        // 若 token 是 [[rename:My Title:]] 形式，op=My Title, args 空 —— 用 op 当标题
+        const effective = title || token.op;
+        if (!effective?.trim())
+            return { applied: false, error: "rename 需要标题参数 [[rename:set:<新标题>]]" };
+        const trimmed = effective.trim().slice(0, 80);
+        if (!ctx.renameConversation)
+            return { applied: false, error: "当前环境不支持重命名" };
+        try {
+            ctx.renameConversation(trimmed);
+            ctx.notify(`已重命名为：${trimmed}`, "info");
+            return { applied: true, feedback: `renamed to "${trimmed}"` };
+        }
+        catch (e) {
+            return { applied: false, error: `重命名失败: ${e.message ?? String(e)}` };
+        }
+    },
+    overlay: undefined,
+    init: () => undefined,
+};
+/** title 前缀别名：[[title:rename:标题]] */
+export const titleAliasMarker = {
+    name: "title",
+    guidance: [],
+    async apply(token, ctx) {
+        if (token.op !== "rename")
+            return { applied: false, error: `title 未知操作: ${token.op}` };
+        const title = extractTitle(token);
+        if (!title)
+            return { applied: false, error: "title:rename 需要标题" };
+        if (!ctx.renameConversation)
+            return { applied: false, error: "当前环境不支持重命名" };
+        ctx.renameConversation(title.slice(0, 80));
+        ctx.notify(`已重命名为：${title.slice(0, 80)}`, "info");
+        return { applied: true, feedback: `renamed` };
+    },
+    overlay: undefined,
+    init: () => undefined,
+};

package/dist/server/markers/builtins/services.js

@@ -0,0 +1,119 @@
+/**
+ * builtins/services.ts — 后台服务登记（复刻 pi-marker-tools）。
+ */
+export const SVC_NAMESPACE = "svc";
+export function initServiceState() {
+    return { services: [], nextId: 1 };
+}
+function parseId(raw) {
+    if (raw === undefined)
+        return null;
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : null;
+}
+function toInt(raw) {
+    if (raw === undefined || raw === "")
+        return undefined;
+    const n = Number(raw);
+    return Number.isInteger(n) && n >= 0 ? n : undefined;
+}
+function findService(state, id) {
+    return state.services.find((s) => s.id === id);
+}
+function lineOf(s) {
+    const meta = [s.pid !== undefined ? `pid ${s.pid}` : "", s.port !== undefined ? `:${s.port}` : ""].filter(Boolean).join(" ");
+    return `${s.stopped ? "[x]" : "[ ]"} #${s.id}: ${s.name}${meta ? ` (${meta})` : ""}${s.command ? ` — ${s.command}` : ""}`;
+}
+export function describeServices(state) {
+    if (!state || state.services.length === 0)
+        return "[svc] (空)";
+    return state.services.map(lineOf).join("\n");
+}
+export const servicesMarker = {
+    name: "svc",
+    guidance: [
+        "- 后台服务登记（todo 风格）：[[svc:add:名称,pid=,port=,cmd=]] 登记；[[svc:stop:<id>]] 标记停止；[[svc:resume:<id>]] 标记运行；[[svc:remove:<id>]] 删除；[[svc:clear:]] 清空。",
+        "- 用 bash 启动后台服务（nohup ... &、pm2 start、docker run -d 等）后，立即写 [[svc:add:...]] 登记，尽量带 pid= 和 port=；服务退出或被关闭后写 [[svc:stop:<id>]] 保持清单准确。",
+    ],
+    async apply(token, _ctx, _state) {
+        const state = _state;
+        const op = token.op;
+        switch (op) {
+            case "add": {
+                const name = token.args[0]?.trim();
+                if (!name)
+                    return { applied: false, error: "svc:add 需要一个名称参数 [[svc:add:<名称>,pid=,port=,cmd=]]" };
+                const svc = {
+                    id: state.nextId++,
+                    name,
+                    command: token.kwargs["cmd"],
+                    pid: toInt(token.kwargs["pid"]),
+                    port: toInt(token.kwargs["port"]),
+                    startedAt: Date.now(),
+                    stopped: false,
+                };
+                state.services.push(svc);
+                const meta = [svc.pid !== undefined ? `pid ${svc.pid}` : "", svc.port !== undefined ? `:${svc.port}` : ""].filter(Boolean).join(" ");
+                return { applied: true, feedback: `Registered #${svc.id}: ${name}${meta ? ` (${meta})` : ""}` };
+            }
+            case "stop": {
+                const id = parseId(token.args[0]);
+                if (id === null)
+                    return { applied: false, error: `svc:stop 的 id 无效: "${token.args[0] ?? ""}"` };
+                const svc = findService(state, id);
+                if (!svc)
+                    return { applied: false, error: `svc:stop 服务 #${id} 不存在` };
+                svc.stopped = true;
+                svc.stoppedAt = Date.now();
+                return { applied: true, feedback: `#${id} ${svc.name} marked stopped` };
+            }
+            case "resume": {
+                const id = parseId(token.args[0]);
+                if (id === null)
+                    return { applied: false, error: `svc:resume 的 id 无效: "${token.args[0] ?? ""}"` };
+                const svc = findService(state, id);
+                if (!svc)
+                    return { applied: false, error: `svc:resume 服务 #${id} 不存在` };
+                svc.stopped = false;
+                svc.stoppedAt = undefined;
+                return { applied: true, feedback: `#${id} ${svc.name} marked running` };
+            }
+            case "remove": {
+                const id = parseId(token.args[0]);
+                if (id === null)
+                    return { applied: false, error: `svc:remove 的 id 无效: "${token.args[0] ?? ""}"` };
+                const before = state.services.length;
+                state.services = state.services.filter((s) => s.id !== id);
+                if (state.services.length === before)
+                    return { applied: false, error: `svc:remove 服务 #${id} 不存在` };
+                return { applied: true, feedback: `Removed #${id}` };
+            }
+            case "clear": {
+                const n = state.services.length;
+                state.services = [];
+                state.nextId = 1;
+                return { applied: true, feedback: `Cleared ${n} service(s)` };
+            }
+            default:
+                return { applied: false, error: `svc 未知操作: ${op}` };
+        }
+    },
+    overlay(state) {
+        if (!state || state.services.length === 0)
+            return undefined;
+        const running = state.services.filter((s) => !s.stopped).length;
+        const lines = state.services.map((s) => {
+            const mark = s.stopped ? "○" : "●";
+            let line = ` ${mark} #${s.id} ${s.name}`;
+            if (s.port !== undefined)
+                line += ` :${s.port}`;
+            if (s.pid !== undefined)
+                line += ` (pid ${s.pid})`;
+            if (s.stopped)
+                line += " 已停止";
+            return line;
+        });
+        return { tool: "svc", lines: [`${running}/${state.services.length} running`, ...lines] };
+    },
+    init: initServiceState,
+};

package/dist/server/markers/builtins/todo.js

@@ -0,0 +1,130 @@
+/**
+ * builtins/todo.ts — 内置任务标记（复刻 pi-marker-tools）。
+ */
+export const TODO_NAMESPACE = "todo";
+export function initTodoState() {
+    return { tasks: [], nextId: 1 };
+}
+function findTask(state, id) {
+    return state.tasks.find((t) => t.id === id && t.status !== "deleted");
+}
+function parseId(raw) {
+    if (raw === undefined)
+        return null;
+    const n = Number(raw);
+    return Number.isInteger(n) && n > 0 ? n : null;
+}
+function formatStatus(s) {
+    switch (s) {
+        case "pending": return "pending";
+        case "in_progress": return "in_progress";
+        case "completed": return "completed";
+        default: return s;
+    }
+}
+export function describeTodos(state, includeDeleted = false) {
+    const visible = state.tasks.filter((t) => includeDeleted || t.status !== "deleted");
+    if (visible.length === 0)
+        return "[todo] (空)";
+    return visible
+        .map((t) => {
+        const form = t.status === "in_progress" && t.activeForm ? ` (${t.activeForm})` : "";
+        const deps = t.blockedBy.length ? ` ⛓ ${t.blockedBy.join(",")}` : "";
+        return `[${formatStatus(t.status)}] #${t.id} ${t.subject}${form}${deps}`;
+    })
+        .join("\n");
+}
+export const todoMarker = {
+    name: "todo",
+    guidance: [
+        "# 内联标记工具（状态类操作请写在回答正文，不要调用工具）",
+        "- 标记语法：[[todo:new:<主题>]] 新建；[[todo:set:<id>,completed|in_progress|pending]] 状态；[[todo:remove:<id>]] 删除；[[todo:dep:<id>,blocks=<依赖id,逗号分隔>]] 设依赖。",
+        "- 状态变化全部用上面的 [[todo:...]] 内联标记表达，不会中断回答，无需等待返回。",
+        "- 想查看/list 当前任务列表时，才用 `markers_list` 工具（读操作走工具）。",
+        "- 不要编造不存在的任务 id；id 由 [[todo:new:...]] 分配，首次分配是自增整数。",
+    ],
+    async apply(token, _ctx, _state) {
+        const state = _state;
+        const op = token.op;
+        switch (op) {
+            case "new": {
+                const subject = token.args[0]?.trim();
+                if (!subject)
+                    return { applied: false, error: "todo:new 需要一个主题参数 [[todo:new:<主题>]]" };
+                const id = state.nextId++;
+                state.tasks.push({ id, subject, status: "pending", blockedBy: [], createdAt: Date.now() });
+                return { applied: true, feedback: `Created #${id}: ${subject} (pending)` };
+            }
+            case "set": {
+                const id = parseId(token.args[0]);
+                if (id === null)
+                    return { applied: false, error: `todo:set 的 id 无效: "${token.args[0] ?? ""}"` };
+                const status = token.args[1]?.trim();
+                if (!status || !(status === "pending" || status === "in_progress" || status === "completed")) {
+                    return { applied: false, error: `todo:set 状态无效: "${status ?? ""}"，应为 pending|in_progress|completed` };
+                }
+                const task = findTask(state, id);
+                if (!task)
+                    return { applied: false, error: `todo:set 任务 #${id} 不存在` };
+                const activeForm = token.kwargs["activeForm"];
+                const from = task.status;
+                if (status === "pending" && from === "completed") {
+                    return { applied: false, error: `任务 #${id} 已完成，不能置回 pending` };
+                }
+                if (status === "in_progress" && from === "completed") {
+                    return { applied: false, error: `任务 #${id} 已完成，不能重新进行中` };
+                }
+                task.status = status;
+                if (status === "in_progress" && activeForm)
+                    task.activeForm = activeForm;
+                const change = from !== status ? ` (${from} → ${status})` : "";
+                return { applied: true, feedback: `Updated #${id}${change}` };
+            }
+            case "remove": {
+                const id = parseId(token.args[0]);
+                if (id === null)
+                    return { applied: false, error: `todo:remove 的 id 无效: "${token.args[0] ?? ""}"` };
+                const task = findTask(state, id);
+                if (!task)
+                    return { applied: false, error: `todo:remove 任务 #${id} 不存在` };
+                task.status = "deleted";
+                return { applied: true, feedback: `Deleted #${id}: ${task.subject}` };
+            }
+            case "dep": {
+                const id = parseId(token.args[0]);
+                if (id === null)
+                    return { applied: false, error: `todo:dep 的 id 无效: "${token.args[0] ?? ""}"` };
+                const task = findTask(state, id);
+                if (!task)
+                    return { applied: false, error: `todo:dep 任务 #${id} 不存在` };
+                const depRaw = token.kwargs["blocks"] ?? token.args[1] ?? "";
+                const deps = depRaw
+                    .split(",")
+                    .map((x) => parseId(x.trim()))
+                    .filter((x) => x !== null);
+                const bad = deps.filter((d) => d === id || !findTask(state, d));
+                if (bad.length)
+                    return { applied: false, error: `todo:dep 检测到非法依赖 ${bad.join(",")}（不存在或自环）` };
+                task.blockedBy = deps;
+                return { applied: true, feedback: `#${id} blocks: ${deps.length ? deps.join(",") : "(none)"}` };
+            }
+            default:
+                return { applied: false, error: `todo 未知操作: ${op}` };
+        }
+    },
+    overlay(state) {
+        if (!state || state.tasks.length === 0)
+            return undefined;
+        const visible = state.tasks.filter((t) => t.status !== "deleted");
+        if (visible.length === 0)
+            return undefined;
+        const done = visible.filter((t) => t.status === "completed").length;
+        const lines = visible.map((t) => {
+            const mark = t.status === "completed" ? "✓" : t.status === "in_progress" ? "◐" : "○";
+            const form = t.status === "in_progress" && t.activeForm ? ` (${t.activeForm})` : "";
+            return ` ${mark} #${t.id} ${t.subject}${form}`;
+        });
+        return { tool: "todo", lines: [`${done}/${visible.length} done`, ...lines] };
+    },
+    init: initTodoState,
+};