@konglx/rotom 2.21.0

package/dist/master/db/issues.js

@@ -0,0 +1,373 @@
+import { nowBeijing, shiftBeijing } from "../../shared/time.js";
+import { safeJsonParse } from "../../shared/parse.js";
+import { buildUpdate } from "./build-update.js";
+export const issueMethods = {
+    createIssue(issue) {
+        const now = nowBeijing();
+        this.db.prepare(`
+      INSERT INTO issues (id, group_id, title, description, priority, created_by, working_dir, type, slash_command, approval_policy, assigned_to, created_at, repo_url, repo_branch)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(issue.id, issue.groupId, issue.title, issue.description || "", issue.priority || "medium", issue.createdBy, issue.workingDir || null, issue.type || "task", issue.slashCommand || null, issue.approvalPolicy || "rw_allow", issue.assignedTo || null, now, issue.repoUrl || null, issue.repoBranch || null);
+        this.db.prepare(`
+      INSERT INTO issue_events (issue_id, event_type, agent_name, content, created_at)
+      VALUES (?, 'created', ?, '', ?)
+    `).run(issue.id, issue.createdBy, now);
+    },
+    getIssueById(id) {
+        return this.db.prepare("SELECT * FROM issues WHERE id = ?").get(id);
+    },
+    listIssuesByGroup(groupId, status, type) {
+        let sql = "SELECT * FROM issues WHERE group_id = ?";
+        const params = [groupId];
+        if (status) {
+            sql += " AND status = ?";
+            params.push(status);
+        }
+        if (type) {
+            sql += " AND type = ?";
+            params.push(type);
+        }
+        sql += " ORDER BY CASE status WHEN 'in_progress' THEN 0 WHEN 'open' THEN 1 WHEN 'failed' THEN 2 WHEN 'cancelled' THEN 3 WHEN 'completed' THEN 4 ELSE 5 END, created_at DESC";
+        return this.db.prepare(sql).all(...params);
+    },
+    listAllIssues(status) {
+        let sql = "SELECT * FROM issues";
+        const params = [];
+        if (status) {
+            sql += " WHERE status = ?";
+            params.push(status);
+        }
+        sql += " ORDER BY CASE status WHEN 'in_progress' THEN 0 WHEN 'open' THEN 1 WHEN 'failed' THEN 2 WHEN 'cancelled' THEN 3 WHEN 'completed' THEN 4 ELSE 5 END, created_at DESC";
+        return this.db.prepare(sql).all(...params);
+    },
+    /**
+     * 分页拉取 issue。看板每列独立分页(默认首屏 50 条),避免 completed/cancelled
+     * 累积过多时一次性把全表拉到前端。total 是不带 limit/offset 的全量计数,
+     * 给列头展示真实总数;items 是当前页。排序与 listAllIssues 保持一致。
+     */
+    listIssuesPage(opts) {
+        const orderSql = " ORDER BY CASE status WHEN 'in_progress' THEN 0 WHEN 'open' THEN 1 WHEN 'failed' THEN 2 WHEN 'cancelled' THEN 3 WHEN 'completed' THEN 4 ELSE 5 END, created_at DESC";
+        const where = opts.status ? " WHERE status = ?" : "";
+        const params = opts.status ? [opts.status] : [];
+        const total = this.db.prepare(`SELECT COUNT(*) as n FROM issues${where}`).get(...params).n;
+        const items = this.db
+            .prepare(`SELECT * FROM issues${where}${orderSql} LIMIT ? OFFSET ?`)
+            .all(...params, opts.limit, opts.offset);
+        return { items, total };
+    },
+    updateIssueStatus(id, status, extra) {
+        const now = nowBeijing();
+        const built = buildUpdate({
+            table: "issues",
+            sets: {
+                status,
+                assigned_to: extra?.assignedTo,
+                result: extra?.result,
+                error_message: extra?.errorMessage,
+                artifacts: extra?.artifacts !== undefined ? JSON.stringify(extra.artifacts) : undefined,
+                session_id: extra?.sessionId,
+                cli_tool: extra?.cliTool,
+                usage: extra?.usage,
+                model: extra?.model,
+            },
+            where: "id = ?",
+            whereParams: [id],
+            updatedAt: false,
+            extraSets: [
+                { sql: "updated_at = ?", params: [now] },
+                // started_at 只在第一次进 in_progress 时写,后续 progress 事件不覆盖——
+                // 否则最后一次 in_progress(带 result)会把 started_at 推到接近完成时间,
+                // 导致总耗时显示成 0。COALESCE 保留已有值,paused → in_progress 续跑时
+                // 也保留首次开始时间(总耗时含 paused 段,反映"从开始到结束"的真实时长)。
+                ...(status === "in_progress" ? [{ sql: "started_at = COALESCE(started_at, ?)", params: [now] }] : []),
+                ...(status === "completed" || status === "failed" || status === "cancelled"
+                    ? [{ sql: "completed_at = ?", params: [now] }]
+                    : []),
+            ],
+        });
+        if (built)
+            this.db.prepare(built.sql).run(...built.params);
+        // E2ED auto-sync hook: when an issue reaches terminal state, notify
+        // registered listeners so e2ed can advance requirement status.
+        if (status === "completed" || status === "failed" || status === "cancelled") {
+            this._onIssueTerminal?.(id);
+        }
+    },
+    updateIssueWorkingDir(id, workingDir) {
+        this.db.prepare("UPDATE issues SET working_dir = ?, updated_at = ? WHERE id = ?").run(workingDir, nowBeijing(), id);
+    },
+    /**
+     * 覆盖式写入 issues.latest_todos_json。每次 worker 解析到 TodoWrite tool_use
+     * 都调一次(全量替换);是否额外落 issue_event 由调用方(ws-hub)按内容 hash
+     * 去重决定,这里只管快照列。
+     */
+    updateIssueTodos(id, todos) {
+        this.db.prepare("UPDATE issues SET latest_todos_json = ?, updated_at = ? WHERE id = ?").run(JSON.stringify(todos), nowBeijing(), id);
+    },
+    /**
+     * 反查最新绑定到某个 sessionId 的 issue。
+     * session_id 由 migration 013 加入,无 session_id 列的旧 DB 走不到这里。
+     */
+    getLatestIssueBySessionId(sessionId) {
+        return this.db.prepare("SELECT * FROM issues WHERE session_id = ? ORDER BY updated_at DESC LIMIT 1").get(sessionId);
+    },
+    /**
+     * 查该 (cliTool, groupId) 下最新的 issue。Debug Sessions 视图用:
+     * worker SessionStore 跟 issues.session_id 是两条独立路径(SessionStore
+     * 只在 chat 路径更新,issue 执行不写 SessionStore),所以反查
+     * session_id 经常落空。改用 (cliTool, groupId) 取最新一条 issue,展示
+     * 「上次 claude/codex 在这个群里跑了多少 token」更贴近用户预期。
+     */
+    getLatestIssueByCliTool(cliTool, groupId) {
+        return this.db.prepare("SELECT * FROM issues WHERE cli_tool = ? AND group_id = ? ORDER BY updated_at DESC LIMIT 1").get(cliTool, groupId);
+    },
+    /** Atomically claim the next unassigned issue for an executor agent. */
+    claimNextIssue(agentName) {
+        const issue = this.db.prepare(`
+      SELECT i.* FROM issues i
+      JOIN groups g ON g.id = i.group_id
+      WHERE i.status = 'open' AND i.assigned_to IS NULL AND i.type = 'task'
+        AND g.archived_at IS NULL
+      ORDER BY
+        CASE i.priority WHEN 'critical' THEN 0 WHEN 'high' THEN 1 WHEN 'medium' THEN 2 ELSE 3 END,
+        i.created_at ASC
+      LIMIT 1
+    `).get();
+        if (!issue)
+            return undefined;
+        // Atomic update: only claim if still unassigned
+        const now = nowBeijing();
+        const result = this.db.prepare("UPDATE issues SET assigned_to = ?, status = 'in_progress', started_at = ?, updated_at = ? WHERE id = ? AND assigned_to IS NULL").run(agentName, now, now, issue.id);
+        if (result.changes === 0)
+            return undefined;
+        this.db.prepare(`
+      INSERT INTO issue_events (issue_id, event_type, agent_name, content, created_at)
+      VALUES (?, 'assigned', ?, ?, ?)
+    `).run(issue.id, agentName, `Claimed by ${agentName}`, now);
+        return this.getIssueById(issue.id);
+    },
+    addIssueEvent(event) {
+        this.db.prepare(`
+      INSERT INTO issue_events (issue_id, event_type, agent_name, content, metadata, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(event.issueId, event.eventType, event.agentName, event.content || "", JSON.stringify(event.metadata || {}), nowBeijing());
+    },
+    /**
+     * Post a comment/message on an issue, optionally replying to a specific
+     * event (message quoting). Returns the new event ID.
+     */
+    addIssueComment(issueId, agentName, content, replyToId) {
+        const result = this.db.prepare(`
+      INSERT INTO issue_events (issue_id, event_type, agent_name, content, metadata, reply_to_id, created_at)
+      VALUES (?, 'comment', ?, ?, '{}', ?, ?)
+    `).run(issueId, agentName, content, replyToId ?? null, nowBeijing());
+        return Number(result.lastInsertRowid);
+    },
+    /**
+     * Get all comment messages for an issue, with reply-to resolution (quoted
+     * message content + author embedded in the result).
+     */
+    getIssueMessages(issueId) {
+        const rows = this.db.prepare(`
+      SELECT * FROM issue_events
+      WHERE issue_id = ? AND event_type = 'comment'
+      ORDER BY created_at ASC
+    `).all(issueId);
+        return rows.map((r) => {
+            const msg = {
+                id: r.id,
+                event_type: r.event_type,
+                agent_name: r.agent_name,
+                content: r.content,
+                created_at: r.created_at,
+                metadata: r.metadata,
+                reply_to_id: r.reply_to_id,
+            };
+            if (r.reply_to_id != null) {
+                const quoted = this.db.prepare("SELECT id, agent_name, content, created_at FROM issue_events WHERE id = ?").get(r.reply_to_id);
+                msg.quoted = quoted ?? null;
+            }
+            return msg;
+        });
+    },
+    // 拉取 issue 的事件流。
+    //
+    // 旧实现是 SELECT * ORDER BY created_at ASC LIMIT 200,在 issue 跑久了
+    // events 累积超过 200 条时(典型如 worker 流式喷了大量 [status:thinking]
+    // progress chunk)会把**最新**的事件截掉 —— 用户的追加指令(appended)
+    // 即便已经入库、worker 已消费,也永远拉不回来,前端 reload 多少次都看不到。
+    // 参见 issue 2284adfa 的复现。
+    //
+    // 现在:把事件拆成两类分别处理:
+    //   - 非 progress(created/assigned/appended/approval_request/completed/failed/...)
+    //     是用户关心的关键节点,**全部保留**,不受 limit 影响。
+    //   - progress(worker 流式输出)条数最多,保留**最早 headKeep 条 + 最新
+    //     tailKeep 条**,中间被省略的部分用 event_type='progress_truncated' 的
+    //     虚拟事件标注,前端渲染成「已省略 N 条早期进展」chip。
+    getIssueEvents(issueId, headKeep = 5, tailKeep = 300) {
+        const nonProgress = this.db.prepare("SELECT * FROM issue_events WHERE issue_id = ? AND event_type != 'progress' ORDER BY created_at ASC, id ASC").all(issueId);
+        // 拉全部 progress 在 JS 层过滤纯 status-only 噪声。典型 /plan 任务里
+        // 60% 的 progress chunk 是 [status:thinking]Working/Running/Done[/status:thinking]
+        // 重复几百次 —— hoistStatus 只取 bucket 内最后一个 status 渲染 pill,
+        // 中间的全是冗余。过滤掉它们让 head/tail 截断预算花在有意义的 exec/result/text
+        // 上,大幅减少「已省略 N 条早期进展」的 N。保留最后一条 status-only
+        // 事件,确保 hoistStatus 能取到最终状态(Done/Answered)而不是过时的 Running。
+        const allProgress = this.db.prepare("SELECT * FROM issue_events WHERE issue_id = ? AND event_type = 'progress' ORDER BY id ASC").all(issueId);
+        const STATUS_OPEN = "[status:thinking]";
+        const STATUS_CLOSE = "[/status:thinking]";
+        const isStatusOnly = (c) => {
+            if (!c.startsWith(STATUS_OPEN))
+                return false;
+            const closeIdx = c.indexOf(STATUS_CLOSE, STATUS_OPEN.length);
+            if (closeIdx === -1)
+                return false;
+            return c.slice(closeIdx + STATUS_CLOSE.length).trim() === "";
+        };
+        let lastStatusId = -1;
+        for (let i = allProgress.length - 1; i >= 0; i--) {
+            if (isStatusOnly(allProgress[i].content || "")) {
+                lastStatusId = allProgress[i].id;
+                break;
+            }
+        }
+        const filtered = allProgress.filter(ev => !isStatusOnly(ev.content || "") || ev.id === lastStatusId);
+        const progressCount = filtered.length;
+        // 过滤后的有意义事件数不超过 head+tail,直接全返回,不需要 marker。
+        if (progressCount <= headKeep + tailKeep) {
+            return mergeIssueEvents([...nonProgress, ...filtered]);
+        }
+        const head = filtered.slice(0, headKeep);
+        const tail = filtered.slice(filtered.length - tailKeep);
+        // 截断后 tail 的开头可能落在某条 [tool-result:exec] 上 —— 它配对的
+        // [tool:exec] 在被丢掉的中间段,Dashboard 拿到这条孤儿 result 会渲染成
+        // "(unknown)" 命令卡片(整段子代理输出挂在一条无名的命令下)。从 tail
+        // 头部开始丢弃 result chunk,直到遇到第一条 [tool:exec](之后 tail 内部
+        // FIFO 配对就能正常工作)。status-thinking / 纯文本等非 result chunk
+        // 不影响配对,保留。被丢的 result 计入 omitted,marker 仍提示"已省略"。
+        //
+        // 用 startsWith 而不是 includes:executor 每条 progress chunk 都以单个
+        // tag 开头([tool:exec] / [tool-result:exec] / [status:thinking] / 纯文本),
+        // 起始位置 0 的 tag 一定是真 tag。而 includes 会被 result 内容里出现的
+        // 字面量 "[tool:exec]"(比如 grep 命令把源码里的 tag 字符串匹配出来)
+        // 误判成 exec chunk,导致孤儿 result 没被丢掉。
+        let seenExec = false;
+        const trimmedTail = [];
+        for (const ev of tail) {
+            const c = ev.content || "";
+            if (!seenExec && c.startsWith("[tool:exec]"))
+                seenExec = true;
+            if (!seenExec && c.startsWith("[tool-result:exec]"))
+                continue;
+            trimmedTail.push(ev);
+        }
+        const omitted = progressCount - head.length - trimmedTail.length;
+        // marker 插在 head 最后一条之后、tail 第一条之前。
+        // created_at 取 head 末尾 +1ms,确保排序落在 head 和 tail 之间。
+        const markerTime = head.length > 0
+            ? shiftBeijing(head[head.length - 1].created_at, 1)
+            : (trimmedTail[0]?.created_at ?? nowBeijing());
+        const marker = {
+            id: -1,
+            issue_id: issueId,
+            event_type: "progress_truncated",
+            agent_name: "",
+            content: "",
+            metadata: JSON.stringify({ omitted }),
+            created_at: markerTime,
+            reply_to_id: null,
+        };
+        return mergeIssueEvents([...nonProgress, ...head, marker, ...trimmedTail]);
+    },
+    /** Get a single issue event by its ID. */
+    getIssueEventById(eventId) {
+        return this.db.prepare("SELECT * FROM issue_events WHERE id = ?").get(eventId);
+    },
+    /** Get all issue events for a group (across all issues in that group) */
+    getIssueEventsByGroup(groupId, limit = 500) {
+        return this.db.prepare("SELECT ie.* FROM issue_events ie JOIN issues i ON ie.issue_id = i.id WHERE i.group_id = ? ORDER BY ie.created_at ASC LIMIT ?").all(groupId, limit);
+    },
+    /**
+     * Approvals piggy-back on issue_events (event_type='approval_request') —
+     * their lifecycle ("pending" → "accepted"/"denied") lives inside the JSON
+     * metadata column. Finding one requires a scan + JSON parse since approvalId
+     * isn't indexed; the per-issue event count is small (capped at ~200) so this
+     * is fine in practice.
+     */
+    findApprovalEvent(issueId, approvalId) {
+        const rows = this.db.prepare("SELECT * FROM issue_events WHERE issue_id = ? AND event_type = 'approval_request' ORDER BY created_at DESC").all(issueId);
+        for (const row of rows) {
+            try {
+                const meta = JSON.parse(row.metadata || "{}");
+                if (meta.approvalId === approvalId)
+                    return row;
+            }
+            catch { /* malformed metadata — skip */ }
+        }
+        return undefined;
+    },
+    /** Mark an approval event as resolved. Returns true if the row was updated.
+     *  When `feedback` is provided and status is `denied`, it is persisted in
+     *  metadata so the dashboard can render the rejection reason on the
+     *  resolved card. */
+    updateApprovalStatus(eventId, status, resolvedBy, feedback) {
+        const row = this.db.prepare("SELECT metadata FROM issue_events WHERE id = ?").get(eventId);
+        if (!row)
+            return false;
+        const meta = safeJsonParse(row.metadata, {});
+        meta.status = status;
+        meta.resolvedBy = resolvedBy;
+        meta.resolvedAt = nowBeijing();
+        if (status === "denied" && feedback)
+            meta.feedback = feedback;
+        const result = this.db.prepare("UPDATE issue_events SET metadata = ? WHERE id = ?").run(JSON.stringify(meta), eventId);
+        return result.changes > 0;
+    },
+    deleteIssue(id) {
+        this.db.prepare("DELETE FROM issue_events WHERE issue_id = ?").run(id);
+        this.db.prepare("DELETE FROM issues WHERE id = ?").run(id);
+    },
+    updateIssuePriority(id, priority) {
+        const built = buildUpdate({
+            table: "issues",
+            sets: { priority },
+            where: "id = ?",
+            whereParams: [id],
+            updatedAt: "beijing",
+        });
+        if (built)
+            this.db.prepare(built.sql).run(...built.params);
+    },
+    // 同时支持 title / description 的部分更新。两个字段都不传时返回 false。
+    // 标题在调用方已经做过非空校验，这里只负责落库。
+    updateIssueContent(id, fields) {
+        const built = buildUpdate({
+            table: "issues",
+            sets: {
+                title: fields.title,
+                description: fields.description,
+                slash_command: fields.slashCommand,
+                approval_policy: fields.approvalPolicy,
+            },
+            where: "id = ?",
+            whereParams: [id],
+            updatedAt: "beijing",
+        });
+        if (!built)
+            return false;
+        const result = this.db.prepare(built.sql).run(...built.params);
+        return result.changes > 0;
+    },
+};
+/**
+ * Sort events by created_at then id. Pulled out of getIssueEvents so the
+ * head/tail/all paths can share the merge logic without a class-level helper.
+ */
+function mergeIssueEvents(rows) {
+    return rows.sort((a, b) => {
+        const ta = Date.parse(a.created_at);
+        const tb = Date.parse(b.created_at);
+        if (ta !== tb)
+            return ta - tb;
+        return a.id - b.id;
+    });
+}

package/dist/master/db/links.js

@@ -0,0 +1,221 @@
+/**
+ * Links — 链接主表 / 出现记录 / 标签 / 来源群 / 巡检 run-log CRUD。
+ *
+ * 采集路径(inline hook):
+ *   collectLinksFromText → extractUrls + normalizeUrl → dedup by url_norm
+ *   命中已有 link: addLinkOccurrence + touchLinkLastSeen + (可选)addLinkSourceGroup
+ *   新 link:createLink + addLinkOccurrence + addLinkSourceGroup
+ *
+ * 分类路径(link-patrol scheduled task + 巡检员 agent):
+ *   listUnclassifiedLinks → handler 拼 prompt → pushIssueAssignment
+ *   → agent 完成 issue → handleLinkPatrolIssueTerminal 解析 result → updateLinkClassification
+ *
+ * Methods attach via Object.assign(见 internal.ts)。
+ */
+import { nowBeijing } from "../../shared/time.js";
+import { buildUpdate } from "./build-update.js";
+// ─── Methods ──────────────────────────────────────────────────────────────
+export const linkMethods = {
+    // ─── Link 主表 ────────────────────────────────────────────────────────
+    /** INSERT OR IGNORE,命中 UNIQUE(url_norm) 时返回 undefined。 */
+    createLink(input) {
+        const now = nowBeijing();
+        this.db.prepare(`
+      INSERT OR IGNORE INTO links (id, url_norm, url_raw, title, category, summary, host, created_at, updated_at, last_seen_at)
+      VALUES (?, ?, ?, NULL, NULL, NULL, ?, ?, ?, ?)
+    `).run(input.id, input.urlNorm, input.urlRaw, input.host, now, now, now);
+    },
+    getLinkByUrlNorm(urlNorm) {
+        return this.db.prepare("SELECT * FROM links WHERE url_norm = ?").get(urlNorm);
+    },
+    getLink(id) {
+        return this.db.prepare("SELECT * FROM links WHERE id = ?").get(id);
+    },
+    /** 更新 last_seen_at + updated_at。同 link 多次出现时累加 occurrence 后调。 */
+    touchLinkLastSeen(id) {
+        const now = nowBeijing();
+        this.db.prepare("UPDATE links SET last_seen_at = ?, updated_at = ? WHERE id = ?").run(now, now, id);
+    },
+    /** 巡检员写分类结果。tags 为空数组时清空标签。 */
+    updateLinkClassification(id, fields) {
+        // 1. UPDATE links 主表(category / title / summary)
+        const built = buildUpdate({
+            table: "links",
+            sets: {
+                category: fields.category,
+                title: fields.title,
+                summary: fields.summary,
+            },
+            where: "id = ?",
+            whereParams: [id],
+            updatedAt: "beijing",
+        });
+        if (built)
+            this.db.prepare(built.sql).run(...built.params);
+        // 2. tags 多对多:传了就重写(先 DELETE 再 INSERT)
+        if (Array.isArray(fields.tags)) {
+            this.db.prepare("DELETE FROM link_tags WHERE link_id = ?").run(id);
+            if (fields.tags.length > 0) {
+                const stmt = this.db.prepare("INSERT OR IGNORE INTO link_tags (link_id, tag) VALUES (?, ?)");
+                for (const tag of fields.tags) {
+                    if (typeof tag === "string" && tag.trim())
+                        stmt.run(id, tag.trim());
+                }
+            }
+        }
+        return true;
+    },
+    /** 列表过滤。tag 过滤走 link_tags JOIN;search 在 url_raw / title / host 上 LIKE。 */
+    listLinks(filter = {}) {
+        const { category, tag, search, groupId, host, limit = 50, offset = 0, } = filter;
+        const where = [];
+        const params = [];
+        if (category) {
+            where.push("category = ?");
+            params.push(category);
+        }
+        if (host) {
+            where.push("host = ?");
+            params.push(host);
+        }
+        if (search) {
+            where.push("(url_raw LIKE ? OR title LIKE ? OR host LIKE ?)");
+            const kw = `%${search}%`;
+            params.push(kw, kw, kw);
+        }
+        if (tag) {
+            where.push("id IN (SELECT link_id FROM link_tags WHERE tag = ?)");
+            params.push(tag);
+        }
+        if (groupId) {
+            where.push("id IN (SELECT link_id FROM link_source_groups WHERE group_id = ?)");
+            params.push(groupId);
+        }
+        const whereClause = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+        params.push(limit, offset);
+        return this.db.prepare(`SELECT * FROM links ${whereClause} ORDER BY last_seen_at DESC LIMIT ? OFFSET ?`).all(...params);
+    },
+    countLinks(filter = {}) {
+        const { category, tag, search, groupId, host } = filter;
+        const where = [];
+        const params = [];
+        if (category) {
+            where.push("category = ?");
+            params.push(category);
+        }
+        if (host) {
+            where.push("host = ?");
+            params.push(host);
+        }
+        if (search) {
+            where.push("(url_raw LIKE ? OR title LIKE ? OR host LIKE ?)");
+            const kw = `%${search}%`;
+            params.push(kw, kw, kw);
+        }
+        if (tag) {
+            where.push("id IN (SELECT link_id FROM link_tags WHERE tag = ?)");
+            params.push(tag);
+        }
+        if (groupId) {
+            where.push("id IN (SELECT link_id FROM link_source_groups WHERE group_id = ?)");
+            params.push(groupId);
+        }
+        const whereClause = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+        const row = this.db.prepare(`SELECT COUNT(*) as n FROM links ${whereClause}`).get(...params);
+        return row?.n ?? 0;
+    },
+    /** 取未分类链接(category IS NULL)按 last_seen_at desc,scheduler handler 用。 */
+    listUnclassifiedLinks(limit = 20) {
+        return this.db.prepare(`
+      SELECT l.*, (
+        SELECT context_snippet FROM link_occurrences
+        WHERE link_id = l.id
+        ORDER BY occurred_at ASC
+        LIMIT 1
+      ) AS first_context
+      FROM links l
+      WHERE l.category IS NULL
+      ORDER BY l.last_seen_at DESC
+      LIMIT ?
+    `).all(limit);
+    },
+    // ─── Tags ─────────────────────────────────────────────────────────────
+    listTagsForLink(linkId) {
+        const rows = this.db.prepare("SELECT tag FROM link_tags WHERE link_id = ? ORDER BY tag").all(linkId);
+        return rows.map((r) => r.tag);
+    },
+    // ─── Occurrences ──────────────────────────────────────────────────────
+    addLinkOccurrence(linkId, input) {
+        const id = (`occ_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`);
+        this.db.prepare(`
+      INSERT INTO link_occurrences (id, link_id, source_type, source_id, source_group_id, source_sender, context_snippet, occurred_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(id, linkId, input.sourceType, input.sourceId ?? null, input.sourceGroupId ?? null, input.sourceSender ?? null, input.contextSnippet ?? null, nowBeijing());
+    },
+    listOccurrencesForLink(linkId, limit = 50) {
+        return this.db.prepare("SELECT * FROM link_occurrences WHERE link_id = ? ORDER BY occurred_at DESC LIMIT ?").all(linkId, limit);
+    },
+    // ─── Source groups(多对多)────────────────────────────────────────────
+    addLinkSourceGroup(linkId, groupId) {
+        this.db.prepare("INSERT OR IGNORE INTO link_source_groups (link_id, group_id) VALUES (?, ?)").run(linkId, groupId);
+    },
+    listSourceGroupsForLink(linkId) {
+        const rows = this.db.prepare("SELECT group_id FROM link_source_groups WHERE link_id = ?").all(linkId);
+        return rows.map((r) => r.group_id);
+    },
+    // ─── Patrol runs / logs ───────────────────────────────────────────────
+    createLinkPatrolRun(input) {
+        const now = input.startedAt ?? nowBeijing();
+        this.db.prepare(`
+      INSERT INTO link_patrol_runs
+        (run_id, patrol_group_id, patrol_issue_id, started_at, finished_at, candidates_scanned, candidates_classified, status, note)
+      VALUES (?, ?, ?, ?, NULL, ?, 0, ?, NULL)
+    `).run(input.runId, input.patrolGroupId, input.patrolIssueId ?? null, now, input.candidatesScanned ?? 0, input.status ?? "dispatched");
+    },
+    finishLinkPatrolRun(runId, status, opts) {
+        const built = buildUpdate({
+            table: "link_patrol_runs",
+            sets: {
+                candidates_classified: opts?.classified,
+                note: opts?.note,
+            },
+            where: "run_id = ?",
+            whereParams: [runId],
+            updatedAt: false,
+            extraSets: [
+                { column: "finished_at", value: nowBeijing() },
+                { column: "status", value: status },
+            ],
+        });
+        if (built)
+            this.db.prepare(built.sql).run(...built.params);
+    },
+    getLinkPatrolRunByIssueId(patrolIssueId) {
+        return this.db.prepare("SELECT * FROM link_patrol_runs WHERE patrol_issue_id = ? ORDER BY started_at DESC LIMIT 1").get(patrolIssueId);
+    },
+    getLinkPatrolRun(runId) {
+        return this.db.prepare("SELECT * FROM link_patrol_runs WHERE run_id = ?").get(runId);
+    },
+    listLinkPatrolRuns(opts) {
+        const limit = Math.min(opts?.limit ?? 50, 500);
+        const where = [];
+        const params = [];
+        if (opts?.patrolGroupId) {
+            where.push("patrol_group_id = ?");
+            params.push(opts.patrolGroupId);
+        }
+        const whereClause = where.length > 0 ? `WHERE ${where.join(" AND ")}` : "";
+        params.push(limit);
+        return this.db.prepare(`SELECT * FROM link_patrol_runs ${whereClause} ORDER BY started_at DESC LIMIT ?`).all(...params);
+    },
+    insertLinkPatrolLog(input) {
+        this.db.prepare(`
+      INSERT INTO link_patrol_logs
+        (id, run_id, link_id, category, tags, title, rationale, raw, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(input.id, input.runId, input.linkId ?? null, input.category, input.tags ? JSON.stringify(input.tags) : null, input.title ?? null, input.rationale ?? null, input.raw ?? null, nowBeijing());
+    },
+    listLinkPatrolLogsForRun(runId) {
+        return this.db.prepare("SELECT * FROM link_patrol_logs WHERE run_id = ? ORDER BY created_at ASC").all(runId);
+    },
+};

package/dist/master/db/master-node.js

@@ -0,0 +1,43 @@
+/**
+ * master_node — 本机 master 的身份行(单行表)。
+ *
+ * 由 OPC bootstrap 在 master 启动时调用 `upsertMasterNode` 写入,
+ * 包含 masterId(8 字符 base36,永远稳定)、hostname(显示用)、role 等。
+ */
+export const masterNodeMethods = {
+    getMasterNode() {
+        return this.db.prepare("SELECT * FROM master_node LIMIT 1").get();
+    },
+    /**
+     * 写入或覆盖本机 master 身份行。表是单行的(LIMIT 1),
+     * 调用方应保证一个进程只调一次(首次启动写入,之后只读)。
+     */
+    upsertMasterNode(input) {
+        const existing = this.db.prepare("SELECT id FROM master_node LIMIT 1").get();
+        if (existing) {
+            this.db.prepare(`
+        UPDATE master_node SET
+          hostname = ?,
+          role = ?,
+          display_name = COALESCE(?, display_name),
+          endpoint = COALESCE(?, endpoint),
+          team_name = COALESCE(?, team_name),
+          updated_at = datetime('now')
+        WHERE id = ?
+      `).run(input.hostname, input.role, input.displayName ?? null, input.endpoint ?? null, input.teamName ?? null, existing.id);
+            return;
+        }
+        this.db.prepare(`
+      INSERT INTO master_node (id, hostname, role, display_name, endpoint, team_name)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(input.id, input.hostname, input.role, input.displayName ?? null, input.endpoint ?? null, input.teamName ?? null);
+    },
+    updateMasterRole(role) {
+        this.db.prepare("UPDATE master_node SET role = ?, updated_at = datetime('now') WHERE 1=1").run(role);
+    },
+    /** 本机 master 的 hostname —— 用于 agents 复合键查询时注入 hostname。 */
+    getLocalHostname() {
+        const row = this.db.prepare("SELECT hostname FROM master_node LIMIT 1").get();
+        return row?.hostname;
+    },
+};