@lemoncat7/dsh-partner 1.0.0 → 1.3.9

package/lib/agent-runtime.js

@@ -1,28 +1,61 @@
 import { randomUUID } from 'node:crypto';
-import { mkdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { mkdir, realpath, stat, writeFile } from 'node:fs/promises';
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { BlockAssembler, createToolResultMessage, createUserMessage } from '@deepseek-ai/dsh-llm';
+import { createScope, scopeOf } from '@deepseek-ai/dsh-scope';
+import { concernObservationPrompt } from './autonomy.js';
+import { boundedConcernCheckMinutes } from './concern-domain.js';
+import { PARTNER_MEDIA_MAX_BYTES, safeMediaName } from './channel-message.js';
+import { listConcernFileSources } from './concern-sources.js';
+import { CONCERN_CREATED_NOTICE, renderConcernCreatedNotice } from './concern-notification.js';
+const HEARTBEAT_TIMEOUT_MS = 115_000;
+const HEARTBEAT_DISCOVERY_BUDGET_MS = 72_000;
+const HEARTBEAT_TOOL_TIMEOUT_MS = 18_000;
+const HEARTBEAT_WEB_TOOL_TIMEOUT_MS = 30_000;
+const HEARTBEAT_TOOL_RESULT_LIMIT = 5_000;
+const HEARTBEAT_KNOWLEDGE_RESULT_LIMIT = 8_000;
+const HEARTBEAT_WEB_FETCH_RESULT_LIMIT = 40_000;
+const HEARTBEAT_WEB_SOURCE_RESULT_LIMIT = 125_000;
+const HEARTBEAT_AUDIT_INPUT_LIMIT = 320;
+const HEARTBEAT_AUDIT_OUTPUT_LIMIT = 520;
+const HEARTBEAT_READ_ONLY_TOOLS = new Set([
+    'knowledge_base_search',
+    'knowledge_search',
+    'knowledge_read',
+    'web_search',
+    'web_fetch',
+    'web_source',
+    'glob',
+    'grep',
+    'read',
+]);
+const HEARTBEAT_FILE_UPDATE_TOOLS = new Set(['write', 'edit', 'str_replace_editor']);
+const HEARTBEAT_TOOLS = new Set([...HEARTBEAT_READ_ONLY_TOOLS, ...HEARTBEAT_FILE_UPDATE_TOOLS]);
 export class PartnerAgentRuntime {
     ctx;
     store;
     defaultCwd;
     memory;
     reflection;
+    concerns;
     handles = new Map();
     queues = new Map();
+    heartbeatQueues = new Map();
+    steeringQueues = new Map();
     workspaces = new Map();
-    constructor(ctx, store, defaultCwd, memory, reflection) {
+    constructor(ctx, store, defaultCwd, memory, reflection, concerns) {
         this.ctx = ctx;
         this.store = store;
         this.defaultCwd = defaultCwd;
         this.memory = memory;
         this.reflection = reflection;
+        this.concerns = concerns;
     }
-    async reply(companion, channelId, userId, text) {
+    async reply(companion, channelId, userId, message) {
         const key = `${channelId}:${userId}`;
         const previous = this.queues.get(key) ?? Promise.resolve();
-        let output = '';
-        const current = previous.catch(() => { }).then(async () => { output = await this.drive(companion, channelId, userId, text); });
+        let output = { text: '', attachments: [] };
+        const current = previous.catch(() => { }).then(async () => { output = await this.drive(companion, channelId, userId, message); });
         this.queues.set(key, current);
         try {
             await current;
@@ -33,6 +66,46 @@ export class PartnerAgentRuntime {
                 this.queues.delete(key);
         }
     }
+    async steer(companion, channelId, userId, message) {
+        const key = `${channelId}:${userId}`;
+        const previous = this.steeringQueues.get(key) ?? Promise.resolve();
+        let accepted = false;
+        const current = previous.catch(() => { }).then(async () => { accepted = await this.deliverSteering(companion, channelId, userId, message); });
+        this.steeringQueues.set(key, current);
+        try {
+            await current;
+            return accepted;
+        }
+        finally {
+            if (this.steeringQueues.get(key) === current)
+                this.steeringQueues.delete(key);
+        }
+    }
+    async deliverSteering(companion, channelId, userId, message) {
+        const route = this.store.snapshot().sessions.find(item => item.channelId === channelId && item.userId === userId && item.companionId === companion.id);
+        if (route === undefined)
+            return false;
+        const agent = this.handles.get(route.sessionId)?.agent ?? this.ctx.agents.get(route.sessionId);
+        if (agent === undefined || agent.status !== 'running')
+            return false;
+        const inbound = await this.persistInbound(route, message);
+        const recalled = await this.memory?.recall(companion.id, memoryScope(channelId, userId), inbound.query, 12).catch(() => []);
+        if (recalled && recalled.length > 0)
+            agent.inject(createUserMessage({
+                content: [{ type: 'text', text: renderMemory(recalled) }],
+                source: { kind: 'plugin', plugin: '@lemoncat7/dsh-partner', form: 'notice', summary: '伙伴为插话召回了相关长期记忆' },
+            }));
+        const deferred = await this.concerns?.deferred(companion.id, memoryScope(channelId, userId), inbound.query, 2).catch(() => []);
+        if (deferred && deferred.length > 0) {
+            agent.inject(createUserMessage({
+                content: [{ type: 'text', text: renderDeferredMentions(deferred) }],
+                source: { kind: 'plugin', plugin: '@lemoncat7/dsh-partner', form: 'notice', summary: '伙伴想起了与当前消息相关的挂念' },
+            }));
+            await this.concerns?.markMentioned(companion.id, deferred.map(item => item.id)).catch(() => { });
+        }
+        agent.steer(createUserMessage({ content: inbound.content, source: { kind: 'user' } }));
+        return true;
+    }
     async prepareSession(routeId) {
         const route = this.store.snapshot().sessions.find(item => item.id === routeId);
         if (route === undefined)
@@ -58,29 +131,106 @@ export class PartnerAgentRuntime {
         });
         return next;
     }
-    async heartbeat(companion, route) {
+    async heartbeat(companion, route, concerns) {
         const key = `${route.channelId}:${route.userId}`;
-        const previous = this.queues.get(key) ?? Promise.resolve();
-        let output;
-        const current = previous.catch(() => { }).then(async () => { output = await this.driveHeartbeat(companion, route); });
-        this.queues.set(key, current);
+        const queued = this.heartbeatQueues.get(key);
+        if (queued !== undefined)
+            return queued;
+        const current = this.runHeartbeatWhenIdle(key, companion, route, concerns);
+        this.heartbeatQueues.set(key, current);
         try {
-            await current;
-            return output;
+            return await current;
         }
         finally {
-            if (this.queues.get(key) === current)
-                this.queues.delete(key);
+            if (this.heartbeatQueues.get(key) === current)
+                this.heartbeatQueues.delete(key);
+        }
+    }
+    async persistKnowledgeObservations(companion, route, concerns, observations) {
+        const service = this.ctx.get('dshKnowledgeTracking');
+        if (service === undefined || observations.length === 0)
+            return;
+        const agent = await this.ensureAgent(companion, route);
+        const byId = new Map(concerns.map(item => [item.id, item]));
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(new Error('知识库观察记录超时')), 30_000);
+        timeout.unref?.();
+        try {
+            for (const observation of observations) {
+                if (observation.decision === 'drop')
+                    continue;
+                const concern = byId.get(observation.concernId);
+                if (concern === undefined)
+                    continue;
+                const references = concern.resources.filter(item => item.kind === 'knowledge').map(item => item.locator).slice(0, 4);
+                if (references.length === 0 && concern.watchKind !== 'knowledge')
+                    continue;
+                for (const reference of references.length > 0 ? references : [undefined]) {
+                    await service.record(agent, {
+                        id: observation.id,
+                        subject: concern.subject,
+                        event: observation.event,
+                        evidence: observation.evidence,
+                        source: observation.source,
+                        ...(reference === undefined ? {} : { reference }),
+                        at: observation.createdAt,
+                    }, controller.signal).catch(error => {
+                        this.ctx.logger.warn(`dsh-partner: knowledge observation fell back to local storage: ${errorMessage(error)}`);
+                    });
+                }
+            }
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async concernSources(companion, query = '') {
+        const routes = this.store.snapshot().sessions
+            .filter(item => item.companionId === companion.id)
+            .sort((left, right) => right.lastMessageAt - left.lastMessageAt);
+        const root = routes[0]?.cwd ?? partnerCwd(this.defaultCwd, companion.id);
+        const files = await listConcernFileSources(root, query, 24);
+        const service = this.ctx.get('dshKnowledgeTracking');
+        if (service?.list === undefined || routes[0] === undefined)
+            return files;
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(new Error('知识文档候选查询超时')), 8_000);
+        timeout.unref?.();
+        try {
+            const route = routes[0];
+            const knowledge = await service.list({ session: { id: route.sessionId, header: { cwd: root }, events: [] } }, query, 16, controller.signal).catch(error => {
+                this.ctx.logger.warn(`dsh-partner: knowledge concern sources unavailable: ${errorMessage(error)}`);
+                return [];
+            });
+            return [...files, ...knowledge].slice(0, 40);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async runHeartbeatWhenIdle(key, companion, route, concerns) {
+        for (;;) {
+            await this.queues.get(key)?.catch(() => { });
+            const conversation = await this.ensureAgent(companion, route);
+            if (conversation.status !== 'idle')
+                await conversation.whenIdle();
+            const stableSeq = conversation.session.seq;
+            await delay(2_000);
+            if (this.queues.has(key))
+                continue;
+            if (conversation.status !== 'idle' || conversation.session.seq !== stableSeq)
+                continue;
+            return this.driveScopedHeartbeat(conversation, companion, concerns);
         }
     }
     async observeSessionEvent(session, event) {
-        if (event.type !== 'turn/end' || event.data.reason.kind !== 'completed' || this.reflection === undefined)
+        if (event.type !== 'turn/end' || event.data.reason.kind !== 'completed')
             return;
         const route = this.store.snapshot().sessions.find(item => item.sessionId === session.id);
         if (route === undefined)
             return;
         const companion = this.store.snapshot().companions.find(item => item.id === route.companionId);
-        if (companion === undefined || !companion.automation.memory.enabled)
+        if (companion === undefined)
             return;
         const events = completedTurnEvents(session.events, event);
         const prompt = events.find(item => item.type === 'user/message' && item.data.source.kind === 'user');
@@ -89,42 +239,89 @@ export class PartnerAgentRuntime {
         const assistantText = replies.flatMap(item => item.type === 'assistant/message' ? [textContent(item.data.message.content)] : []).filter(Boolean).join('\n\n');
         if (!userText || !assistantText)
             return;
-        await this.reflection.reflect(companion, {
-            id: `turn-${randomUUID()}`, companionId: companion.id, scopeId: memoryScope(route.channelId, route.userId),
+        const scopeId = memoryScope(route.channelId, route.userId);
+        const concernDirective = await this.concerns?.applyUserDirective(companion.id, scopeId, userText, event.time);
+        if (!companion.automation.memory.enabled || this.reflection === undefined)
+            return;
+        const created = await this.reflection.reflect(companion, {
+            id: `turn-${randomUUID()}`, companionId: companion.id, scopeId,
             sessionId: session.id, at: event.time, user: userText, assistant: assistantText,
+            ...(concernDirective === undefined ? {} : { concernDirective }),
         });
+        if (created.length > 0)
+            await this.recordConcernCreatedNotice(companion, scopeId, created).catch(error => {
+                this.ctx.logger.warn(`dsh-partner: automatic concern creation notice failed: ${errorMessage(error)}`);
+            });
         await this.store.update(state => {
             const target = state.sessions.find(item => item.id === route.id);
             if (target)
                 target.lastMessageAt = Date.now();
         });
     }
-    async driveHeartbeat(companion, route) {
-        const agent = await this.ensureAgent(companion, route);
-        if (agent.status !== 'idle')
-            return undefined;
-        const recalled = await this.memory?.recall(companion.id, memoryScope(route.channelId, route.userId), '未完成任务 承诺 跟进 风险 提醒', 16).catch(() => []);
-        if (recalled && recalled.length > 0)
-            agent.inject(createUserMessage({
-                content: [{ type: 'text', text: renderMemory(recalled) }],
-                source: { kind: 'plugin', plugin: '@lemoncat7/dsh-partner', form: 'notice', summary: '心跳召回相关长期记忆' },
-            }));
-        const startSeq = agent.session.seq;
-        agent.followup(createUserMessage({
-            content: [{ type: 'text', text: [
-                        '执行一次伙伴心跳检查。结合当前会话、召回的结构化记忆、每日回顾和可用工具，判断现在是否确实有一条值得主动告诉用户的信息。',
-                        '检查范围：用户明确交代但尚未完成的事项、承诺过的后续跟进、临近风险，以及通过当前已挂载知识库或工具获得的真正有用的新发现。',
-                        '所有主动报告必须能从当前会话、该联系人的结构化记忆、每日回顾或工具结果中找到依据；不得为了活跃而寒暄，不得虚构进展，不得重复近期提醒。',
-                        '如果没有必要通知，只回复：NO_ACTION',
-                        '如果需要通知，只输出准备发送给用户的简短中文消息，不要解释这是心跳。',
-                    ].join('\n') }],
-            source: { kind: 'plugin', plugin: '@lemoncat7/dsh-partner', form: 'notice', summary: '伙伴正在进行低打扰心跳检查' },
-        }));
-        await agent.whenIdle();
-        const response = extractAssistantText(agent, startSeq).trim();
-        if (!response || /^NO_ACTION[。.!！]?$/i.test(response))
-            return undefined;
-        return response;
+    async recordConcernCreatedNotice(companion, scopeId, concerns) {
+        if (concerns.length === 0)
+            return false;
+        const route = this.store.snapshot().sessions
+            .filter(item => item.companionId === companion.id && memoryScope(item.channelId, item.userId) === scopeId)
+            .sort((left, right) => right.lastMessageAt - left.lastMessageAt)[0];
+        if (route === undefined)
+            return false;
+        const conversation = await this.ensureAgent(companion, route);
+        if (conversation.status !== 'idle')
+            await conversation.whenIdle();
+        conversation.session.append('user/message', createUserMessage({
+            content: [{ type: 'text', text: renderConcernCreatedNotice(concerns) }],
+            source: { kind: 'plugin', plugin: '@lemoncat7/dsh-partner', form: 'notice', summary: CONCERN_CREATED_NOTICE },
+        }), { surfaceOp: 'append' });
+        return true;
+    }
+    async driveScopedHeartbeat(conversation, companion, concerns) {
+        const scope = await createHeartbeatScope(this.ctx, conversation, concerns);
+        try {
+            return await this.driveEphemeralHeartbeat(scope.agent, companion, concerns);
+        }
+        finally {
+            await scope.dispose();
+        }
+    }
+    async driveEphemeralHeartbeat(agent, companion, concerns) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(new Error('伙伴心跳超过安全时限')), HEARTBEAT_TIMEOUT_MS);
+        timeout.unref?.();
+        try {
+            const execution = await runHeartbeatInference(this.ctx, agent, companion, concerns, controller.signal);
+            return controller.signal.aborted
+                ? { ...execution, error: '伙伴心跳超过安全时限，已收束并终止' }
+                : execution;
+        }
+        catch (error) {
+            const now = Date.now();
+            return {
+                concerns,
+                candidates: [],
+                startedAt: now,
+                completedAt: now,
+                tools: [],
+                error: controller.signal.aborted ? '伙伴心跳超过安全时限，已收束并终止' : errorMessage(error),
+            };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async recordHeartbeatActivity(companion, route, execution, outcome, deliveryError) {
+        const conversation = await this.ensureAgent(companion, route);
+        if (conversation.status !== 'idle')
+            await conversation.whenIdle();
+        conversation.session.append('user/message', createUserMessage({
+            content: [{ type: 'text', text: renderHeartbeatActivity(execution, outcome, deliveryError) }],
+            source: {
+                kind: 'plugin',
+                plugin: '@lemoncat7/dsh-partner',
+                form: 'notice',
+                summary: '伙伴正在进行低打扰心跳检查',
+            },
+        }), { surfaceOp: 'append' });
     }
     async resetCompanion(companionId) {
         await this.releaseCompanion(companionId);
@@ -153,21 +350,30 @@ export class PartnerAgentRuntime {
     async close() {
         await Promise.all([...this.handles.values()].map(handle => handle.dispose().catch(() => { })));
         this.handles.clear();
+        this.heartbeatQueues.clear();
+        this.steeringQueues.clear();
     }
-    async drive(companion, channelId, userId, text) {
+    async drive(companion, channelId, userId, message) {
         const session = await this.ensureSession(companion, channelId, userId);
         const agent = await this.ensureAgent(companion, session);
         if (agent.status !== 'idle')
             await agent.whenIdle();
-        const recalled = await this.memory?.recall(companion.id, memoryScope(channelId, userId), text, 12).catch(() => []);
+        const inbound = await this.persistInbound(session, message);
+        const recalled = await this.memory?.recall(companion.id, memoryScope(channelId, userId), inbound.query, 12).catch(() => []);
         if (recalled && recalled.length > 0)
             agent.inject(createUserMessage({
                 content: [{ type: 'text', text: renderMemory(recalled) }],
                 source: { kind: 'plugin', plugin: '@lemoncat7/dsh-partner', form: 'notice', summary: '伙伴回忆了与当前消息相关的长期记忆' },
             }));
+        const deferred = await this.concerns?.deferred(companion.id, memoryScope(channelId, userId), inbound.query, 2).catch(() => []);
+        if (deferred && deferred.length > 0)
+            agent.inject(createUserMessage({
+                content: [{ type: 'text', text: renderDeferredMentions(deferred) }],
+                source: { kind: 'plugin', plugin: '@lemoncat7/dsh-partner', form: 'notice', summary: '伙伴想起了与当前消息相关的挂念' },
+            }));
         const startSeq = agent.session.seq;
         agent.followup(createUserMessage({
-            content: [{ type: 'text', text }],
+            content: inbound.content,
             source: { kind: 'user' },
         }));
         await agent.whenIdle();
@@ -179,7 +385,35 @@ export class PartnerAgentRuntime {
         });
         if (!response)
             throw new Error('伙伴没有生成可发送的文本回复');
-        return response;
+        if (deferred && deferred.length > 0)
+            await this.concerns?.markMentioned(companion.id, deferred.map(item => item.id)).catch(() => { });
+        return { text: response, attachments: await extractOutboundAttachments(response, session.cwd ?? this.defaultCwd) };
+    }
+    async persistInbound(session, message) {
+        const cwd = session.cwd ?? this.defaultCwd;
+        const directory = join(cwd, 'inbound');
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const content = [];
+        const notes = [];
+        for (const attachment of message.attachments) {
+            if (attachment.data.byteLength > PARTNER_MEDIA_MAX_BYTES)
+                throw new Error('微信附件超过 64 MB 限制');
+            const name = `${Date.now()}-${randomUUID().slice(0, 8)}-${safeMediaName(attachment.name)}`;
+            const path = join(directory, name);
+            await writeFile(path, attachment.data, { flag: 'wx', mode: 0o600 });
+            notes.push(`微信${attachment.kind === 'image' ? '图片' : '文档'}已保存：${path}`);
+            if (attachment.kind === 'image') {
+                const mediaType = attachment.mediaType;
+                const ref = await this.ctx.attachments.saveImage({ data: attachment.data, mediaType, name: attachment.name });
+                content.push({ type: 'image', attachment: ref });
+            }
+        }
+        const visibleText = [message.text.trim(), ...notes].filter(Boolean).join('\n\n');
+        if (visibleText)
+            content.unshift({ type: 'text', text: visibleText });
+        if (content.length === 0)
+            content.push({ type: 'text', text: '[微信附件消息]' });
+        return { content, query: [message.text, ...message.attachments.map(item => item.name)].filter(Boolean).join(' ') };
     }
     async ensureSession(companion, channelId, userId) {
         const existing = this.store.snapshot().sessions.find(item => item.channelId === channelId && item.userId === userId);
@@ -271,6 +505,65 @@ export class PartnerAgentRuntime {
         await (await workspace).attachSession(route.sessionId);
     }
 }
+function delay(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+export async function extractOutboundAttachments(text, cwd) {
+    const candidates = new Set();
+    for (const match of text.matchAll(/\[[^\]]*\]\((?:<)?(file:\/\/)?([^)>]+)(?:>)?\)/g)) {
+        const value = decodeURIComponent(match[2] ?? '').trim();
+        if (value)
+            candidates.add(value);
+    }
+    for (const match of text.matchAll(/`([^`\n]+)`/g)) {
+        const value = match[1]?.trim();
+        if (value && mediaTypeFor(value))
+            candidates.add(value);
+    }
+    for (const line of text.split('\n').map(item => item.trim())) {
+        const value = line.replace(/^`|`$/g, '');
+        if (value.startsWith('/') && !value.includes(' '))
+            candidates.add(value);
+    }
+    const root = await realpath(cwd);
+    const result = [];
+    const included = new Set();
+    for (const candidate of candidates) {
+        if (result.length >= 8)
+            break;
+        const target = resolve(root, candidate);
+        let actual;
+        try {
+            actual = await realpath(target);
+        }
+        catch {
+            continue;
+        }
+        if (included.has(actual))
+            continue;
+        const rel = relative(root, actual);
+        if (rel.startsWith('..') || rel === '..' || resolve(root, rel) !== actual)
+            continue;
+        const info = await stat(actual);
+        if (!info.isFile() || info.size > PARTNER_MEDIA_MAX_BYTES)
+            continue;
+        const mediaType = mediaTypeFor(actual);
+        if (!mediaType)
+            continue;
+        included.add(actual);
+        result.push({ path: actual, name: basename(actual), mediaType, kind: mediaType.startsWith('image/') ? 'image' : 'file' });
+    }
+    return result;
+}
+function mediaTypeFor(path) {
+    return {
+        '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp',
+        '.pdf': 'application/pdf', '.doc': 'application/msword', '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+        '.xls': 'application/vnd.ms-excel', '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        '.ppt': 'application/vnd.ms-powerpoint', '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+        '.txt': 'text/plain', '.md': 'text/markdown', '.csv': 'text/csv', '.json': 'application/json', '.zip': 'application/zip',
+    }[extname(path).toLowerCase()];
+}
 export function completedTurnEvents(events, end) {
     let startSeq;
     for (let index = events.length - 1; index >= 0; index -= 1) {
@@ -293,6 +586,12 @@ function renderMemory(entries) {
         ...entries.map(entry => `- [${entry.kind}｜置信度 ${entry.confidence.toFixed(2)}] ${entry.subject}：${entry.content}`),
     ].join('\n');
 }
+function renderDeferredMentions(entries) {
+    return [
+        '伙伴之前发现了与用户当前消息相关的新变化。若自然且确实有帮助，可以在本次回答末尾顺手提一句；不要抢占当前问题，也不要声称刚刚搜索。',
+        ...entries.map(item => `- ${item.event}${item.evidence ? `（依据：${item.evidence}）` : ''}`),
+    ].join('\n');
+}
 export function resolveAgentOptions(defaultModel, companion) {
     return {
         ...defaultModel.currentSelection(),
@@ -314,7 +613,327 @@ export function renewedSession(previous, now = Date.now()) {
 export function partnerCwd(root, companionId) {
     return join(root, 'partners', companionId);
 }
-function renderPersona(companion) {
+async function createHeartbeatScope(ctx, conversation, concerns) {
+    const parent = scopeOf(conversation.ctx);
+    if (parent === undefined)
+        throw new Error('伙伴心跳无法解析当前 Agent 作用域');
+    const availableTools = [...HEARTBEAT_TOOLS].filter(name => ctx.tools.get(name, conversation) !== undefined);
+    const policy = heartbeatToolPolicy(concerns, availableTools);
+    const allowedTools = [...policy.allowed];
+    if (allowedTools.length === 0)
+        throw new Error('伙伴心跳没有可用的只读发现工具');
+    const cwd = conversation.session.header.cwd;
+    if (!cwd)
+        throw new Error('伙伴心跳缺少当前伙伴工作目录');
+    const fileAccess = await resolveHeartbeatFileAccess(cwd, concerns);
+    const agent = {};
+    const scope = createScope(ctx, agent, { parent });
+    const agentCtx = scope.ctx.extend({ agent });
+    Object.assign(agent, {
+        id: conversation.id,
+        options: conversation.options,
+        session: conversation.session,
+        inbox: conversation.inbox,
+        status: 'idle',
+        ctx: agentCtx,
+        cancel: () => { },
+        whenIdle: async () => { },
+        runMaintenance: async (job) => job(new AbortController().signal),
+        send: () => { throw new Error('心跳作用域不接受会话消息'); },
+        followup: () => { throw new Error('心跳作用域不接受会话消息'); },
+        steer: () => { throw new Error('心跳作用域不接受会话消息'); },
+        inject: () => { throw new Error('心跳作用域不接受会话消息'); },
+    });
+    agentCtx.tools.presentAs('native');
+    agentCtx.tools.restrict({ allow: allowedTools });
+    agentCtx.tools.guard(exec => {
+        if (!policy.allowed.has(exec.name))
+            return `当前挂念的来源策略不允许调用 ${exec.name}`;
+        return heartbeatToolDenial(exec.name, exec.arguments, fileAccess);
+    });
+    return { agent, dispose: () => scope.dispose() };
+}
+export function heartbeatToolPolicy(concerns, available) {
+    const installed = new Set(available);
+    const hasLinkedFile = concerns.some(item => item.resources?.some(resource => resource.kind === 'file') === true);
+    return {
+        allowed: new Set([...installed].filter(name => HEARTBEAT_READ_ONLY_TOOLS.has(name) || (hasLinkedFile && HEARTBEAT_FILE_UPDATE_TOOLS.has(name)))),
+    };
+}
+async function runHeartbeatInference(ctx, agent, companion, concerns, signal) {
+    const startedAt = Date.now();
+    const traces = [];
+    const discoveryDeadline = startedAt + HEARTBEAT_DISCOVERY_BUDGET_MS;
+    try {
+        const selection = resolveAgentOptions(ctx.agentDefaultModel, companion);
+        if (!selection.provider || !selection.model)
+            throw new Error('伙伴心跳没有可用的模型路由');
+        const tools = ctx.tools.schemas(agent).filter(tool => HEARTBEAT_TOOLS.has(tool.name));
+        if (tools.length === 0)
+            throw new Error('伙伴心跳没有可用的只读发现工具');
+        const messages = [createUserMessage({
+                content: [{ type: 'text', text: concernObservationPrompt(concerns, agent.session.header.cwd) }],
+                source: { kind: 'plugin', plugin: '@lemoncat7/dsh-partner', form: 'notice', summary: '伙伴观察挂念变化' },
+            })];
+        for (;;) {
+            const discoveryOpen = Date.now() < discoveryDeadline;
+            const prepared = await ctx.llm.prepareCall(selection, signal);
+            const assembler = new BlockAssembler();
+            for await (const chunk of prepared.stream({
+                ...prepared.config,
+                messages,
+                system: renderPersona(companion, 'heartbeat'),
+                tools: discoveryOpen ? tools : [],
+                signal,
+            }))
+                assembler.push(chunk);
+            const finish = assembler.finish;
+            if (finish.kind === 'error' || finish.kind === 'aborted') {
+                throw new Error(`伙伴心跳模型调用失败：${finish.failure.message}`);
+            }
+            const response = assembler.message({ kind: 'model', provider: prepared.config.provider, model: prepared.config.model });
+            messages.push(response);
+            const pending = response.content.filter((block) => block.type === 'tool-call');
+            if (pending.length === 0) {
+                const output = textContent(response.content);
+                return {
+                    concerns,
+                    candidates: parseConcernObservations(output, new Set(concerns.map(item => item.id))),
+                    startedAt,
+                    completedAt: Date.now(),
+                    output,
+                    tools: traces,
+                };
+            }
+            for (const call of pending) {
+                const argumentsValue = boundHeartbeatToolArguments(call.name, parseHeartbeatToolArguments(call));
+                const toolStartedAt = Date.now();
+                const remainingDiscoveryMs = discoveryDeadline - toolStartedAt;
+                const result = remainingDiscoveryMs <= 0
+                    ? { isError: true, content: [{ type: 'text', text: '本轮发现阶段的时间预算已用完，请根据已有结果立即输出最终 Observation JSON。' }] }
+                    : await executeHeartbeatTool(ctx, agent, call, argumentsValue, signal, remainingDiscoveryMs);
+                const toolCompletedAt = Date.now();
+                const visibleContent = heartbeatToolContent(call.name, result.content);
+                traces.push({
+                    name: call.name,
+                    input: auditValue(argumentsValue, HEARTBEAT_AUDIT_INPUT_LIMIT),
+                    output: auditText(textContent(visibleContent) || '工具返回了非文本结果', HEARTBEAT_AUDIT_OUTPUT_LIMIT),
+                    startedAt: toolStartedAt,
+                    completedAt: toolCompletedAt,
+                    status: result.isError ? 'failed' : 'completed',
+                });
+                messages.push(createToolResultMessage({ callId: call.id, content: visibleContent, isError: result.isError }));
+            }
+        }
+    }
+    catch (error) {
+        return { concerns, candidates: [], startedAt, completedAt: Date.now(), tools: traces, error: errorMessage(error) };
+    }
+}
+export function parseConcernObservations(raw, allowedIds) {
+    const match = raw.trim().match(/\{[\s\S]*\}/);
+    if (!match)
+        throw new Error('伙伴心跳没有返回 Observation JSON');
+    const parsed = JSON.parse(match[0]);
+    if (!Array.isArray(parsed.observations))
+        throw new Error('伙伴心跳 Observation 格式无效');
+    const seen = new Set();
+    return parsed.observations.flatMap(value => {
+        if (!isRecord(value))
+            return [];
+        const concernId = typeof value.concernId === 'string' ? value.concernId : '';
+        if (!allowedIds.has(concernId) || seen.has(concernId))
+            return [];
+        seen.add(concernId);
+        const changed = value.changed === true;
+        const nextCheckInMinutes = boundedConcernCheckMinutes(value.nextCheckInMinutes);
+        const notificationRuleEffect = value.notificationRuleEffect === 'notify' || value.notificationRuleEffect === 'suppress'
+            ? value.notificationRuleEffect
+            : 'auto';
+        return [{
+                concernId,
+                changed,
+                event: changed && typeof value.event === 'string' ? value.event.trim().slice(0, 800) : '',
+                evidence: typeof value.evidence === 'string' ? value.evidence.trim().slice(0, 2_000) : '',
+                source: typeof value.source === 'string' ? value.source.trim().slice(0, 240) : '',
+                relevance: boundedScore(value.relevance),
+                confidence: boundedScore(value.confidence),
+                actionability: boundedScore(value.actionability),
+                ...(nextCheckInMinutes === undefined ? {} : { nextCheckInMinutes }),
+                notificationRuleEffect,
+                notificationRuleReason: typeof value.notificationRuleReason === 'string' ? value.notificationRuleReason.trim().slice(0, 800) : '',
+            }];
+    });
+}
+function boundedScore(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : .5;
+}
+function parseHeartbeatToolArguments(call) {
+    try {
+        return JSON.parse(call.arguments);
+    }
+    catch {
+        return { __invalidArguments: call.arguments };
+    }
+}
+async function resolveHeartbeatFileAccess(cwd, concerns) {
+    const root = await realpath(cwd);
+    const writable = new Set();
+    const locators = concerns.flatMap(item => item.resources ?? []).filter(item => item.kind === 'file').map(item => item.locator);
+    for (const locator of new Set(locators)) {
+        const lexical = resolve(root, locator);
+        if (!pathInside(root, lexical) || isPartnerMemoryPath(relative(root, lexical)))
+            continue;
+        try {
+            const actual = await realpath(lexical);
+            const info = await stat(actual);
+            if (!info.isFile() || !pathInside(root, actual) || isPartnerMemoryPath(relative(root, actual)))
+                continue;
+            writable.add(lexical);
+            writable.add(actual);
+        }
+        catch { /* References may become stale; stale files remain read-only and cannot be recreated. */ }
+    }
+    return { root, writable };
+}
+export function heartbeatToolDenial(name, argumentsValue, access) {
+    if (!isRecord(argumentsValue))
+        return undefined;
+    const isRead = ['glob', 'grep', 'read'].includes(name);
+    const isUpdate = HEARTBEAT_FILE_UPDATE_TOOLS.has(name);
+    if (!isRead && !isUpdate)
+        return undefined;
+    const paths = [argumentsValue.path, argumentsValue.file_path].filter((value) => typeof value === 'string');
+    if (paths.some(isPartnerMemoryPath))
+        return '伙伴心跳不能访问长期记忆、挂念数据库、会话归档或其备份目录；请改查普通工作文件或其他安全来源。';
+    if (access && paths.some(value => !pathInside(access.root, resolve(access.root, value))))
+        return '伙伴心跳只能访问当前伙伴工作目录内的文件。';
+    if (!isUpdate)
+        return undefined;
+    if (name === 'str_replace_editor' && argumentsValue.command === 'create')
+        return '心跳只能更新已经关联且现存的 @文件，不能创建新文件。';
+    const target = paths[0];
+    if (paths.length !== 1 || target === undefined || !access || !access.writable.has(resolve(access.root, target))) {
+        return '心跳只能更新当前挂念明确关联的现存 @文件，不能修改其他文件。';
+    }
+    return undefined;
+}
+async function executeHeartbeatTool(ctx, agent, call, argumentsValue, signal, remainingDiscoveryMs) {
+    const configuredTimeoutMs = call.name === 'web_fetch' || call.name === 'web_source' ? HEARTBEAT_WEB_TOOL_TIMEOUT_MS : HEARTBEAT_TOOL_TIMEOUT_MS;
+    const timeoutMs = Math.max(1, Math.min(configuredTimeoutMs, remainingDiscoveryMs));
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const toolSignal = AbortSignal.any([signal, timeoutSignal]);
+    try {
+        return await ctx.tools.execute({ callId: call.id, name: call.name, arguments: argumentsValue, agent, signal: toolSignal });
+    }
+    catch (error) {
+        const message = timeoutSignal.aborted && !signal.aborted
+            ? `工具 ${call.name} 超过 ${timeoutMs / 1_000} 秒，已跳过；请按既有规则判断来源不可用，或根据已有结果收束。`
+            : `工具 ${call.name} 调用失败：${errorMessage(error)}`;
+        return { isError: true, content: [{ type: 'text', text: message }] };
+    }
+}
+function pathInside(root, target) {
+    const value = relative(root, target);
+    return value === '' || (value !== '..' && !value.startsWith(`..${sep}`) && !isAbsolute(value));
+}
+function boundHeartbeatToolArguments(name, value) {
+    if (!isRecord(value))
+        return value;
+    const bounded = { ...value };
+    if (name === 'knowledge_base_search' || name === 'knowledge_search')
+        bounded.limit = boundedInteger(value.limit, 4);
+    if (name === 'knowledge_read')
+        bounded.maxChars = boundedInteger(value.maxChars, HEARTBEAT_KNOWLEDGE_RESULT_LIMIT);
+    if (name === 'web_source')
+        bounded.max_chars = boundedInteger(value.max_chars, 120_000);
+    if (name === 'read')
+        bounded.limit = boundedInteger(value.limit, 80);
+    return bounded;
+}
+function heartbeatToolContent(name, content) {
+    let remaining = heartbeatToolResultLimit(name);
+    const bounded = [];
+    for (const block of content) {
+        if (remaining <= 0)
+            break;
+        if (block.type !== 'text') {
+            bounded.push(block);
+            continue;
+        }
+        const sanitized = name === 'glob'
+            ? block.text.split('\n').filter(line => !isPartnerMemoryPath(line.trim())).join('\n')
+            : block.text;
+        const text = sanitized.length <= remaining ? sanitized : `${sanitized.slice(0, Math.max(0, remaining - 1))}…`;
+        if (text)
+            bounded.push({ ...block, text });
+        remaining -= text.length;
+    }
+    if (bounded.length === 0 && name === 'glob')
+        return [{ type: 'text', text: '未发现可供心跳检查的普通工作文件；伙伴记忆与会话归档已从结果中排除。' }];
+    return bounded;
+}
+function heartbeatToolResultLimit(name) {
+    if (name === 'knowledge_read')
+        return HEARTBEAT_KNOWLEDGE_RESULT_LIMIT;
+    if (name === 'web_fetch')
+        return HEARTBEAT_WEB_FETCH_RESULT_LIMIT;
+    if (name === 'web_source')
+        return HEARTBEAT_WEB_SOURCE_RESULT_LIMIT;
+    return HEARTBEAT_TOOL_RESULT_LIMIT;
+}
+function isPartnerMemoryPath(value) {
+    const normalized = value.replaceAll('\\', '/').replace(/^\.\//, '/');
+    return /(?:^|\/)(?:memory(?:\/|-backup(?:-|\/)|$)|concerns(?:\/|$))/i.test(normalized);
+}
+function boundedInteger(value, maximum) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0 ? Math.min(value, maximum) : maximum;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function renderHeartbeatActivity(execution, outcome, deliveryError) {
+    const status = outcome === 'notified' ? '已通过微信提醒' : outcome === 'quiet' ? '无需主动提醒' : '执行失败';
+    const lines = [
+        `状态：${status}`,
+        `本轮挂念：${execution.concerns.map(item => item.subject).join('；')}`,
+        `用时：${formatDuration(execution.completedAt - execution.startedAt)}`,
+        `工具：${execution.tools.length > 0 ? `${execution.tools.length} 次调用` : '未调用'}`,
+    ];
+    execution.tools.forEach((trace, index) => {
+        lines.push('', `${index + 1}. ${trace.name} · ${trace.status === 'completed' ? '完成' : '失败'} · ${formatDuration(trace.completedAt - trace.startedAt)}`, `输入：${trace.input}`, `结果：${trace.output}`);
+    });
+    const changed = execution.observations ?? [];
+    const conclusion = execution.error || deliveryError
+        ? `失败原因：${deliveryError ?? execution.error}`
+        : changed.length > 0
+            ? `新变化：\n${changed.map(item => `- ${item.event}（${decisionLabel(item.decision)} · ${Math.round(item.interruptScore * 100)}）`).join('\n')}`
+            : '最终结论：本轮没有发现经过校验的新变化。';
+    lines.push('', conclusion);
+    return lines.join('\n');
+}
+function decisionLabel(value) {
+    return value === 'notify' ? '已提醒' : value === 'feed' ? '伙伴动态' : value === 'defer' ? '顺手一提' : value === 'remember' ? '静默记下' : '忽略';
+}
+function auditValue(value, limit) {
+    try {
+        return auditText(JSON.stringify(value), limit);
+    }
+    catch {
+        return auditText(String(value), limit);
+    }
+}
+function auditText(value, limit) {
+    const text = value.trim().replace(/\n{3,}/g, '\n\n');
+    return text.length <= limit ? text : `${text.slice(0, limit - 1)}…`;
+}
+function formatDuration(milliseconds) {
+    if (milliseconds < 1_000)
+        return `${Math.max(0, milliseconds)} ms`;
+    return `${(milliseconds / 1_000).toFixed(milliseconds < 10_000 ? 1 : 0)} 秒`;
+}
+function errorMessage(error) { return error instanceof Error ? error.message : String(error); }
+function renderPersona(companion, surface = 'conversation') {
     const capabilities = companion.capabilities.length > 0 ? companion.capabilities.join('、') : '由当前 Agent Preset 提供的基础能力';
     return [
         `你当前以长期工作伙伴「${companion.name}」的身份工作。`,
@@ -322,7 +941,9 @@ function renderPersona(companion) {
         companion.description ? `定位：${companion.description}` : '',
         companion.instructions ? `长期行为准则：\n${companion.instructions}` : '',
         `用户为此伙伴启用的能力范围：${capabilities}。能力标识不等于授权；只能调用当前会话实际提供且已经通过权限校验的工具。`,
-        '这个会话由 DSH 网页与微信私聊渠道共同使用。保持同一上下文，不要假定每条消息都来自微信；渠道回传由适配器负责。回答兼顾网页与移动端阅读，执行外部操作前继续遵守工具自身的授权与审批边界。',
+        surface === 'heartbeat'
+            ? '这是一轮独立的伙伴心跳，不是用户聊天的延续。只根据本轮真实可读信息行动，最终结果由渠道适配器决定是否发送。'
+            : '这个会话由 DSH 网页与微信私聊渠道共同使用。保持同一上下文，不要假定每条消息都来自微信；渠道回传由适配器负责。回答兼顾网页与移动端阅读，执行外部操作前继续遵守工具自身的授权与审批边界。',
     ].filter(Boolean).join('\n\n');
 }
 export function renderToolProtocol() {
@@ -332,6 +953,7 @@ export function renderToolProtocol() {
         '`run_code` 的程序只返回完成当前任务所需的精简结果。需要顺序依赖时逐个 `await`，互不依赖的只读调用才可并行。',
         '若工具结果提示 “only `run_code` is callable directly”，说明路由方式错误；立即在同一轮改用 `run_code` 重试。只有规范重试也失败时，才向用户说明真正的失败原因。',
         '若当前请求原生暴露了目标工具，则可以直接调用该原生工具；不要臆造未出现在顶层清单或生成 SDK 中的工具。',
+        '需要把生成的图片或文档交给用户时，最终回复必须用 Markdown 链接明确引用伙伴工作目录中的文件，例如 `[下载文件](/绝对路径/文件.pdf)`；不要只说“文件在这里”。渠道会在确认真实路径位于伙伴工作目录后发送附件。',
     ].join('\n');
 }
 function extractAssistantText(agent, fromSeq) {