@fgbg/mdocs 1.3.21 → 1.3.23

package/README.md

@@ -4,7 +4,7 @@
 
 面向个人开发者与小团队：产品内 **智能助手 + 帮写**，外部 **CLI / Skills** 接入 Cursor / Claude；SQLite + 本地文件，**无账户**即可协作。
 
-[文档站点](https://xuhuafeifei.github.io/mdocs-site/) · [GitHub](https://github.com/xuhuafeifei/mdocs) · [npm `@fgbg/mdocs`](https://www.npmjs.com/package/@fgbg/mdocs) · 当前版本 **1.3.21**
+[文档站点](https://xuhuafeifei.github.io/mdocs-site/) · [GitHub](https://github.com/xuhuafeifei/mdocs) · [npm `@fgbg/mdocs`](https://www.npmjs.com/package/@fgbg/mdocs) · 当前版本 **1.3.23**
 
 <p align="center">
   <img src="image/site主页.png" alt="mdocs 文档站点首页" width="860" />

package/agent-skills/changelog/SKILL.md

@@ -10,6 +10,26 @@ source: changelog.md
 
 现行文档里，产品概念「域」已改称 **工作空间**。下面各版本仍按当时的叫法记录。
 
+## v1.3.23
+
+### 智能助手会话
+- 修复历史会话列表偶发「只剩一条」：`session.json` 读改写改为 Manager 方法级串行队列 + 原子写；读失败时从 `*.jsonl` 恢复索引
+- 运维命令：`mdocs agent session repair --dry-run|--confirm`（可加 `--visitor` / `--kind`），把孤儿 transcript 补回列表
+
+### 文档信息
+- 新增 **字符数**：去 Markdown 语法 / HTML 标签后的纯文本总字符（异步统计，回答「写了多少字」）
+
+### 语义模型与日志
+- Embedding GGUF 默认目录改为 `~/.mdocs/embedding/`（随 `MDOCS_DATA_DIR`）；旧 `~/.fgbg/shared/embedding/` 仅作已下载文件回退
+- 文件日志默认只落 **error+**（`MDOCS_LOG_LEVEL` 可改）；路径仍为 `~/.mdocs/logs/`；无前台管理页
+
+## v1.3.22
+
+### 语义索引
+- 构建过程打进度日志（batch / 文档 / chunk 耗时），方便在 console 观察
+- `MDOCS_DISABLE_EMBEDDING=1`：小内存机器可整路关闭语义（仅关键词 FTS）
+- 缺 `node-llama-cpp` 时日志给出重装指引；`mdocs update` 同步新依赖并补装该包
+
 ## v1.3.21
 
 同 v1.3.20（npm 上 1.3.20 卡在 processing，改发此版本）。

package/agent-skills/getting-started-installation/SKILL.md

@@ -77,11 +77,15 @@ mdocs visitor migrate --from Alice --to Bob --dry-run
 
 # 显式启动服务
 mdocs start
+
+# 修复智能助手会话索引（历史列表丢条目时；须 --dry-run 或 --confirm）
+mdocs agent session repair --dry-run
+mdocs agent session repair --confirm
 ```
 
 ## 运行时数据
 
-首次启动后，数据目录自动创建在 `~/.mdocs/`：
+首次启动后，数据目录自动创建在 `~/.mdocs/`（可用 `MDOCS_DATA_DIR` 改根目录）：
 
 ```
 ~/.mdocs/
@@ -94,7 +98,9 @@ mdocs start
         folder/       # 工作空间内子目录（逻辑存在于数据库）
           b.md
     assets/           # 上传的附件
-  logs/               # 运行日志
+  logs/               # 运行日志（默认文件级别 error+，见 MDOCS_LOG_LEVEL）
+  embedding/          # 本地语义模型 GGUF（可用 MDOCS_EMBEDDING_DIR 覆盖）
+  tenant/             # 访客私有运行时（含 agent 会话 jsonl）
 ```
 
 文档以 Lexical JSON 格式存储在 `files/docs/` 中，只能由 mdocs 加载编辑。

package/dist/server/agent/Agent/session-manager.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { randomUUID } from "node:crypto";
 import { getConfig } from "../../config/index.js";
+import { atomicWriteJson, withSessionMetaLock } from "./session-meta-lock.js";
 const SESSION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 /** 空白帮写（无 documentId）的 lastOpened 键 */
 export const CODING_BLANK_DOC_KEY = "__blank__";
@@ -96,7 +97,164 @@ export class AgentSessionManager {
         }
     }
     async writeMeta(meta) {
-        await fs.promises.writeFile(this.metaPath, JSON.stringify(meta, null, 2), "utf8");
+        await atomicWriteJson(this.metaPath, meta);
+    }
+    /**
+     * 从目录内 *.jsonl 重建 sessions 列表（不删文件）。
+     * 用于 meta 损坏 / 被写成只剩一条时的恢复。
+     */
+    async scanTranscriptEntries() {
+        await this.ensureSessionDir();
+        let names = [];
+        try {
+            names = await fs.promises.readdir(this.sessionDir);
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const name of names) {
+            if (!name.endsWith(".jsonl"))
+                continue;
+            const id = name.slice(0, -".jsonl".length);
+            if (!isSessionId(id))
+                continue;
+            const full = this.jsonlPath(id);
+            let updatedAt = nowIso();
+            try {
+                const st = await fs.promises.stat(full);
+                updatedAt = st.mtime.toISOString();
+            }
+            catch {
+                /* ignore */
+            }
+            const title = await this.peekTitleFromTranscript(id);
+            out.push({ id, title, updatedAt });
+        }
+        return out;
+    }
+    async peekTitleFromTranscript(sessionId) {
+        try {
+            const txt = await fs.promises.readFile(this.jsonlPath(sessionId), "utf8");
+            for (const line of txt.split("\n")) {
+                const t = line.trim();
+                if (!t)
+                    continue;
+                try {
+                    const row = JSON.parse(t);
+                    if (row.role === "user" && typeof row.content === "string" && row.content.trim()) {
+                        return titleFromUserContent(row.content);
+                    }
+                }
+                catch {
+                    /* ignore */
+                }
+            }
+        }
+        catch {
+            /* ignore */
+        }
+        return undefined;
+    }
+    /** readMeta 失败或 sessions 空时，用磁盘 jsonl 拼一份可用 meta（不写盘）。 */
+    async recoverMetaFromDisk(preferLastOpened) {
+        const scanned = await this.scanTranscriptEntries();
+        if (scanned.length === 0)
+            return null;
+        const prefer = preferLastOpened && isSessionId(preferLastOpened) && scanned.some((s) => s.id === preferLastOpened)
+            ? preferLastOpened
+            : scanned.slice().sort((a, b) => (a.updatedAt < b.updatedAt ? 1 : -1))[0].id;
+        return {
+            lastOpenedSessionId: prefer,
+            sessions: scanned,
+            lastOpenedByDocument: {},
+        };
+    }
+    /**
+     * Manager 公开方法级串行入口（队列 key = metaPath）。
+     * 所有会动磁盘会话状态的路径只应通过这里，禁止队外裸写。
+     */
+    runSerialized(fn) {
+        return withSessionMetaLock(this.metaPath, fn);
+    }
+    /**
+     * 已在 runSerialized 内：读改写 meta。
+     * read 失败时先从 jsonl 恢复，避免再写成「只剩当前一条」。
+     */
+    async mutateMetaUnlocked(mutator) {
+        let meta = await this.readMeta();
+        if (!meta) {
+            meta =
+                (await this.recoverMetaFromDisk()) ?? {
+                    lastOpenedSessionId: "",
+                    sessions: [],
+                    lastOpenedByDocument: {},
+                };
+        }
+        await mutator(meta);
+        if (!meta.lastOpenedSessionId || !isSessionId(meta.lastOpenedSessionId)) {
+            const fallback = meta.sessions[0]?.id ?? randomUUID();
+            meta.lastOpenedSessionId = fallback;
+            this.ensureSessionEntry(meta, fallback, { touchUpdatedAt: false });
+        }
+        await this.writeMeta(meta);
+        return meta;
+    }
+    /**
+     * 把磁盘上有 jsonl、但 meta.sessions 里没有的条目补回去。
+     * @returns 补入条数
+     */
+    async repairMetaFromDisk(opts) {
+        const dryRun = opts?.dryRun === true;
+        await this.ensureSessionDir();
+        return this.runSerialized(async () => {
+            const existing = await this.readMeta();
+            const scanned = await this.scanTranscriptEntries();
+            const byId = new Map();
+            for (const s of existing?.sessions ?? [])
+                byId.set(s.id, { ...s });
+            let added = 0;
+            for (const s of scanned) {
+                if (byId.has(s.id)) {
+                    const cur = byId.get(s.id);
+                    if (!cur.title?.trim() && s.title)
+                        cur.title = s.title;
+                    if (!cur.updatedAt && s.updatedAt)
+                        cur.updatedAt = s.updatedAt;
+                    continue;
+                }
+                byId.set(s.id, s);
+                added += 1;
+            }
+            const sessions = Array.from(byId.values());
+            const lastOpened = existing?.lastOpenedSessionId && byId.has(existing.lastOpenedSessionId)
+                ? existing.lastOpenedSessionId
+                : sessions.slice().sort((a, b) => ((a.updatedAt ?? "") < (b.updatedAt ?? "") ? 1 : -1))[0]
+                    ?.id ?? randomUUID();
+            if (sessions.length === 0) {
+                return {
+                    before: existing?.sessions.length ?? 0,
+                    after: 0,
+                    added: 0,
+                    sessionDir: this.sessionDir,
+                    dryRun,
+                };
+            }
+            const next = {
+                lastOpenedSessionId: lastOpened,
+                sessions,
+                lastOpenedByDocument: existing?.lastOpenedByDocument,
+            };
+            if (!dryRun)
+                await this.writeMeta(next);
+            return {
+                before: existing?.sessions.length ?? 0,
+                after: sessions.length,
+                added,
+                sessionDir: this.sessionDir,
+                dryRun,
+            };
+        });
     }
     ensureSessionEntry(meta, sessionId, patch) {
         const idx = meta.sessions.findIndex((s) => s.id === sessionId);
@@ -175,134 +333,130 @@ export class AgentSessionManager {
             return [];
         }
     }
-    /**
-     * 确保有可用 lastOpened。
-     * coding + documentId：按文档维度；normal：全局 lastOpened。
-     */
-    async ensureLastOpened(documentId) {
-        await this.ensureSessionDir();
+    /** 已在 runSerialized 内：确保 lastOpened。 */
+    async ensureLastOpenedUnlocked(documentId) {
         if (this.kind !== "coding") {
-            if (this.cachedSessionId)
-                return this.cachedSessionId;
-            const meta = await this.readMeta();
-            if (!meta) {
-                const sessionId = randomUUID();
-                await this.writeMeta({
-                    lastOpenedSessionId: sessionId,
-                    sessions: [{ id: sessionId, updatedAt: nowIso() }],
-                });
-                this.cachedSessionId = sessionId;
-                return sessionId;
-            }
-            this.ensureSessionEntry(meta, meta.lastOpenedSessionId, { touchUpdatedAt: false });
-            await this.writeMeta(meta);
+            const meta = await this.mutateMetaUnlocked((m) => {
+                if (!m.lastOpenedSessionId || !isSessionId(m.lastOpenedSessionId)) {
+                    const sessionId = m.sessions[0]?.id ?? randomUUID();
+                    m.lastOpenedSessionId = sessionId;
+                    this.ensureSessionEntry(m, sessionId, { touchUpdatedAt: false });
+                    return;
+                }
+                this.ensureSessionEntry(m, m.lastOpenedSessionId, { touchUpdatedAt: false });
+            });
             this.cachedSessionId = meta.lastOpenedSessionId;
             return meta.lastOpenedSessionId;
         }
         const key = docScopeKey(documentId);
-        const meta = (await this.readMeta()) ?? {
-            lastOpenedSessionId: "",
-            sessions: [],
-            lastOpenedByDocument: {},
-        };
-        const scoped = this.filterByDocument(meta.sessions, documentId);
-        const mapped = meta.lastOpenedByDocument?.[key];
-        const mappedOk = mapped &&
-            isSessionId(mapped) &&
-            scoped.some((s) => s.id === mapped);
-        if (mappedOk) {
-            meta.lastOpenedSessionId = mapped;
-            this.ensureSessionEntry(meta, mapped, { touchUpdatedAt: false });
-            await this.writeMeta(meta);
-            this.cachedSessionId = mapped;
-            return mapped;
-        }
-        if (scoped[0]) {
-            const sessionId = scoped[0].id;
-            meta.lastOpenedSessionId = sessionId;
-            this.setLastOpenedForDoc(meta, documentId, sessionId);
-            await this.writeMeta(meta);
-            this.cachedSessionId = sessionId;
-            return sessionId;
-        }
-        const sessionId = randomUUID();
-        meta.lastOpenedSessionId = sessionId;
-        this.ensureSessionEntry(meta, sessionId, {
-            touchUpdatedAt: true,
-            documentId: documentId?.trim() ? documentId.trim() : null,
+        const meta = await this.mutateMetaUnlocked((m) => {
+            const scoped = this.filterByDocument(m.sessions, documentId);
+            const mapped = m.lastOpenedByDocument?.[key];
+            const mappedOk = mapped && isSessionId(mapped) && scoped.some((s) => s.id === mapped);
+            if (mappedOk) {
+                m.lastOpenedSessionId = mapped;
+                this.ensureSessionEntry(m, mapped, { touchUpdatedAt: false });
+                return;
+            }
+            if (scoped[0]) {
+                const sessionId = scoped[0].id;
+                m.lastOpenedSessionId = sessionId;
+                this.setLastOpenedForDoc(m, documentId, sessionId);
+                return;
+            }
+            const sessionId = randomUUID();
+            m.lastOpenedSessionId = sessionId;
+            this.ensureSessionEntry(m, sessionId, {
+                touchUpdatedAt: true,
+                documentId: documentId?.trim() ? documentId.trim() : null,
+            });
+            this.setLastOpenedForDoc(m, documentId, sessionId);
         });
-        this.setLastOpenedForDoc(meta, documentId, sessionId);
-        await this.writeMeta(meta);
-        this.cachedSessionId = sessionId;
-        return sessionId;
+        this.cachedSessionId = meta.lastOpenedSessionId;
+        return meta.lastOpenedSessionId;
+    }
+    /**
+     * 确保有可用 lastOpened。
+     * coding + documentId：按文档维度；normal：全局 lastOpened。
+     */
+    async ensureLastOpened(documentId) {
+        await this.ensureSessionDir();
+        if (this.kind !== "coding" && this.cachedSessionId)
+            return this.cachedSessionId;
+        return this.runSerialized(() => this.ensureLastOpenedUnlocked(documentId));
     }
     async listSessions(documentId) {
-        const lastOpenedSessionId = await this.ensureLastOpened(documentId);
-        const meta = (await this.readMeta());
-        const scoped = this.filterByDocument(meta.sessions, documentId);
-        return {
-            lastOpenedSessionId,
-            sessions: this.sortSummaries(scoped),
-        };
+        await this.ensureSessionDir();
+        return this.runSerialized(async () => {
+            const lastOpenedSessionId = await this.ensureLastOpenedUnlocked(documentId);
+            const meta = await this.readMeta();
+            const scoped = this.filterByDocument(meta?.sessions ?? [], documentId);
+            return {
+                lastOpenedSessionId,
+                sessions: this.sortSummaries(scoped),
+            };
+        });
     }
     async loadLastOpenedMessages(documentId) {
-        const sessionId = await this.ensureLastOpened(documentId);
-        return { sessionId, messages: await this.loadTranscript(sessionId) };
+        await this.ensureSessionDir();
+        return this.runSerialized(async () => {
+            const sessionId = await this.ensureLastOpenedUnlocked(documentId);
+            return { sessionId, messages: await this.loadTranscript(sessionId) };
+        });
     }
     /** 新建空会话并设为该文档（或空白桶）的 lastOpened */
     async createSession(documentId) {
         await this.ensureSessionDir();
         const sessionId = randomUUID();
-        const meta = (await this.readMeta()) ?? {
-            lastOpenedSessionId: sessionId,
-            sessions: [],
-            lastOpenedByDocument: {},
-        };
-        meta.lastOpenedSessionId = sessionId;
         const doc = this.kind === "coding"
             ? documentId?.trim()
                 ? documentId.trim()
                 : null
             : undefined;
-        this.ensureSessionEntry(meta, sessionId, {
-            title: "新会话",
-            touchUpdatedAt: true,
-            documentId: doc,
+        return this.runSerialized(async () => {
+            await this.mutateMetaUnlocked((meta) => {
+                meta.lastOpenedSessionId = sessionId;
+                this.ensureSessionEntry(meta, sessionId, {
+                    title: "新会话",
+                    touchUpdatedAt: true,
+                    documentId: doc,
+                });
+                if (this.kind === "coding") {
+                    this.setLastOpenedForDoc(meta, documentId, sessionId);
+                }
+            });
+            this.cachedSessionId = sessionId;
+            return { sessionId, messages: [] };
         });
-        if (this.kind === "coding") {
-            this.setLastOpenedForDoc(meta, documentId, sessionId);
-        }
-        await this.writeMeta(meta);
-        this.cachedSessionId = sessionId;
-        return { sessionId, messages: [] };
     }
     /** 切换 lastOpened；coding 时可校验属于同一 documentId */
     async openSession(sessionId, documentId) {
         if (!isSessionId(sessionId))
             throw new Error("invalid_session_id");
         await this.ensureSessionDir();
-        const meta = await this.readMeta();
-        const inMeta = Boolean(meta?.sessions.some((s) => s.id === sessionId));
-        const hasFile = fs.existsSync(this.jsonlPath(sessionId));
-        if (!inMeta && !hasFile)
-            throw new Error("session_not_found");
-        const next = meta ?? { lastOpenedSessionId: sessionId, sessions: [], lastOpenedByDocument: {} };
-        const entry = next.sessions.find((s) => s.id === sessionId);
-        if (this.kind === "coding" && documentId !== undefined) {
-            const want = docScopeKey(documentId);
-            const have = entry ? entryDocKey(entry) : CODING_BLANK_DOC_KEY;
-            if (want !== have)
-                throw new Error("session_document_mismatch");
-        }
-        next.lastOpenedSessionId = sessionId;
-        this.ensureSessionEntry(next, sessionId, { touchUpdatedAt: true });
-        if (this.kind === "coding") {
-            const bindDoc = entry?.documentId ?? (documentId !== undefined ? documentId : null);
-            this.setLastOpenedForDoc(next, bindDoc, sessionId);
-        }
-        await this.writeMeta(next);
-        this.cachedSessionId = sessionId;
-        return { sessionId, messages: await this.loadTranscript(sessionId) };
+        return this.runSerialized(async () => {
+            await this.mutateMetaUnlocked((meta) => {
+                const inMeta = meta.sessions.some((s) => s.id === sessionId);
+                const hasFile = fs.existsSync(this.jsonlPath(sessionId));
+                if (!inMeta && !hasFile)
+                    throw new Error("session_not_found");
+                const entry = meta.sessions.find((s) => s.id === sessionId);
+                if (this.kind === "coding" && documentId !== undefined) {
+                    const want = docScopeKey(documentId);
+                    const have = entry ? entryDocKey(entry) : CODING_BLANK_DOC_KEY;
+                    if (want !== have)
+                        throw new Error("session_document_mismatch");
+                }
+                meta.lastOpenedSessionId = sessionId;
+                this.ensureSessionEntry(meta, sessionId, { touchUpdatedAt: true });
+                if (this.kind === "coding") {
+                    const bindDoc = entry?.documentId ?? (documentId !== undefined ? documentId : null);
+                    this.setLastOpenedForDoc(meta, bindDoc, sessionId);
+                }
+            });
+            this.cachedSessionId = sessionId;
+            return { sessionId, messages: await this.loadTranscript(sessionId) };
+        });
     }
     /**
      * 空白帮写写回成文后：把 session 绑到新 documentId，并设为该文 lastOpened。
@@ -316,49 +470,43 @@ export class AgentSessionManager {
         if (!doc)
             throw new Error("document_id_required");
         await this.ensureSessionDir();
-        const meta = (await this.readMeta()) ?? {
-            lastOpenedSessionId: sessionId,
-            sessions: [],
-            lastOpenedByDocument: {},
-        };
-        const inMeta = meta.sessions.some((s) => s.id === sessionId);
-        const hasFile = fs.existsSync(this.jsonlPath(sessionId));
-        if (!inMeta && !hasFile)
-            throw new Error("session_not_found");
-        this.ensureSessionEntry(meta, sessionId, {
-            documentId: doc,
-            touchUpdatedAt: true,
+        return this.runSerialized(async () => {
+            await this.mutateMetaUnlocked((meta) => {
+                const inMeta = meta.sessions.some((s) => s.id === sessionId);
+                const hasFile = fs.existsSync(this.jsonlPath(sessionId));
+                if (!inMeta && !hasFile)
+                    throw new Error("session_not_found");
+                this.ensureSessionEntry(meta, sessionId, {
+                    documentId: doc,
+                    touchUpdatedAt: true,
+                });
+                meta.lastOpenedSessionId = sessionId;
+                this.setLastOpenedForDoc(meta, doc, sessionId);
+                if (meta.lastOpenedByDocument?.[CODING_BLANK_DOC_KEY] === sessionId) {
+                    delete meta.lastOpenedByDocument[CODING_BLANK_DOC_KEY];
+                }
+            });
+            this.cachedSessionId = sessionId;
+            return { sessionId, documentId: doc };
         });
-        meta.lastOpenedSessionId = sessionId;
-        this.setLastOpenedForDoc(meta, doc, sessionId);
-        // 从空白桶 lastOpened 清掉自己（若仍指向本 session）
-        if (meta.lastOpenedByDocument?.[CODING_BLANK_DOC_KEY] === sessionId) {
-            delete meta.lastOpenedByDocument[CODING_BLANK_DOC_KEY];
-        }
-        await this.writeMeta(meta);
-        this.cachedSessionId = sessionId;
-        return { sessionId, documentId: doc };
     }
-    async touchLastOpened(sessionId, patch) {
-        const meta = (await this.readMeta()) ?? {
-            lastOpenedSessionId: sessionId,
-            sessions: [],
-            lastOpenedByDocument: {},
-        };
-        meta.lastOpenedSessionId = sessionId;
-        const existing = meta.sessions.find((s) => s.id === sessionId);
-        const needTitle = patch?.titleIfEmpty &&
-            !(existing?.title && existing.title.trim() && existing.title !== "新会话");
-        this.ensureSessionEntry(meta, sessionId, {
-            title: needTitle ? patch.titleIfEmpty : undefined,
-            touchUpdatedAt: true,
+    async touchLastOpenedUnlocked(sessionId, patch) {
+        await this.mutateMetaUnlocked((meta) => {
+            meta.lastOpenedSessionId = sessionId;
+            const existing = meta.sessions.find((s) => s.id === sessionId);
+            const needTitle = patch?.titleIfEmpty &&
+                !(existing?.title && existing.title.trim() && existing.title !== "新会话");
+            this.ensureSessionEntry(meta, sessionId, {
+                title: needTitle ? patch.titleIfEmpty : undefined,
+                touchUpdatedAt: true,
+            });
+            if (this.kind === "coding") {
+                this.setLastOpenedForDoc(meta, existing?.documentId ?? null, sessionId);
+            }
         });
-        if (this.kind === "coding") {
-            this.setLastOpenedForDoc(meta, existing?.documentId ?? null, sessionId);
-        }
-        await this.writeMeta(meta);
         this.cachedSessionId = sessionId;
     }
+    /** jsonl append + touch meta 同一 Manager 队列任务。 */
     async appendUser(sessionId, content, skillNames) {
         if (!isSessionId(sessionId))
             throw new Error("invalid_session_id");
@@ -370,14 +518,20 @@ export class AgentSessionManager {
         const row = { role: "user", content, ts: nowIso() };
         if (names.length > 0)
             row.skillNames = names;
-        await fs.promises.appendFile(this.jsonlPath(sessionId), JSON.stringify(row) + "\n", "utf8");
-        await this.touchLastOpened(sessionId, { titleIfEmpty: titleFromUserContent(content) });
+        await this.runSerialized(async () => {
+            await fs.promises.appendFile(this.jsonlPath(sessionId), JSON.stringify(row) + "\n", "utf8");
+            await this.touchLastOpenedUnlocked(sessionId, {
+                titleIfEmpty: titleFromUserContent(content),
+            });
+        });
     }
     async appendAssistant(sessionId, content) {
         if (!isSessionId(sessionId))
             throw new Error("invalid_session_id");
-        await fs.promises.appendFile(this.jsonlPath(sessionId), JSON.stringify({ role: "assistant", content, ts: nowIso() }) + "\n", "utf8");
-        await this.touchLastOpened(sessionId);
+        await this.runSerialized(async () => {
+            await fs.promises.appendFile(this.jsonlPath(sessionId), JSON.stringify({ role: "assistant", content, ts: nowIso() }) + "\n", "utf8");
+            await this.touchLastOpenedUnlocked(sessionId);
+        });
     }
 }
 export async function getAgentSessionForApi(visitorId, kind = "normal", documentId) {
@@ -395,4 +549,60 @@ export async function openAgentSessionForApi(visitorId, sessionId, kind = "norma
 export async function bindCodingSessionDocumentForApi(visitorId, sessionId, documentId) {
     return new AgentSessionManager(visitorId, { kind: "coding" }).bindSessionDocument(sessionId, documentId);
 }
+/** 修复单个访客的 normal / coding session meta（按 kind）。 */
+export async function repairAgentSessionsForVisitor(params) {
+    const kinds = params.kind === "coding"
+        ? ["coding"]
+        : params.kind === "normal"
+            ? ["normal"]
+            : ["normal", "coding"];
+    const rows = [];
+    for (const kind of kinds) {
+        const mgr = new AgentSessionManager(params.visitorId, { kind });
+        const r = await mgr.repairMetaFromDisk({ dryRun: params.dryRun });
+        rows.push({
+            visitorId: params.visitorId,
+            kind,
+            sessionDir: r.sessionDir,
+            before: r.before,
+            after: r.after,
+            added: r.added,
+            dryRun: r.dryRun,
+        });
+    }
+    return rows;
+}
+/** 扫描 dataDir/tenant/*，修复全部（或指定）访客的 session 索引。 */
+export async function repairAgentSessionsUnderDataDir(params) {
+    const { dataDir } = getConfig();
+    const tenantRoot = path.join(dataDir, "tenant");
+    let visitorIds = [];
+    if (params.visitorId) {
+        visitorIds = [params.visitorId];
+    }
+    else {
+        try {
+            visitorIds = (await fs.promises.readdir(tenantRoot)).filter((name) => {
+                try {
+                    return fs.statSync(path.join(tenantRoot, name)).isDirectory();
+                }
+                catch {
+                    return false;
+                }
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    const out = [];
+    for (const visitorId of visitorIds) {
+        out.push(...(await repairAgentSessionsForVisitor({
+            visitorId,
+            kind: params.kind ?? "all",
+            dryRun: params.dryRun,
+        })));
+    }
+    return out;
+}
 //# sourceMappingURL=session-manager.js.map