Files
Agent-Workbench/src/core/research-manager.mjs
T
2026-10-30 20:34:54 +08:00

207 lines
20 KiB
JavaScript

import path from 'node:path';
import { createHash, randomUUID } from 'node:crypto';
import { ReaAdapter, REA_OPERATIONS, resolveReaInstallation } from './tools/rea-adapter.mjs';
import { RESEARCH_ACTIVE, researchError, researchFileIdentity, researchTargetContract, bindReaEvidence,
researchPointer, sealResearchDocument, readResearchDocument } from '../shared/contracts/research.mjs';
import { artifactPage } from './context/read-budget.mjs';
import { createResearchOutputDirectory } from './tools/research-output.mjs';
import { assertMcpResolved } from './tools/mcp-contract.mjs';
const at = () => new Date().toISOString();
const sha = text => createHash('sha256').update(text, 'utf8').digest('hex');
const jobContract = job => ({ schemaVersion: 1, id: job.id, sessionId: job.sessionId, projectId: job.projectId,
taskId: job.taskId, runId: job.runId, targetId: job.targetId, targetSha256: job.targetSha256, operation: job.operation,
evidenceId: job.evidenceId, evidence: job.evidence, bundle: job.bundle, raw: job.raw, contractArtifactId: job.contractArtifactId,
contractSha256: job.contractSha256, installation: job.installation, before: job.before, after: job.after, reusedFromJobId: job.reusedFromJobId ?? null });
export class ResearchManager {
constructor(store, { appDirectory = process.cwd(), installation = null, adapterFactory = (profile, options) => new ReaAdapter(profile, options),
projectBusy = () => false, redact = value => String(value), timeoutMs = 60000 } = {}) {
this.store = store; this.appDirectory = appDirectory; this.installation = installation; this.adapterFactory = adapterFactory;
this.projectBusy = projectBusy; this.redact = redact; this.timeoutMs = timeoutMs;
this.active = new Map(); this.projects = new Map();
}
availability() { return this.installation ?? resolveReaInstallation(this.appDirectory); }
isActive(sessionId) { return [...this.active.values()].some(value => value.sessionId === sessionId); }
projectActive(projectId) { return this.projects.has(projectId); }
reserve(session, id, { source = 'user', signal } = {}) {
assertMcpResolved(this.store, session.projectId);
if (this.projectActive(session.projectId) || this.projectBusy(session.projectId, source === 'agent' ? session.id : null)) throw researchError('当前项目还有任务或研究在执行,请等待结束。');
const controller = new AbortController(), combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
const active = { sessionId: session.id, projectId: session.projectId, controller, signal: combined };
this.active.set(id, active); this.projects.set(session.projectId, id); return active;
}
release(id, active) { this.active.delete(id); if (this.projects.get(active.projectId) === id) this.projects.delete(active.projectId); }
async register(session, input) {
if (!input || typeof input.path !== 'string' || input.label !== undefined && (typeof input.label !== 'string' || input.label.length > 160)
|| input.goal !== undefined && (typeof input.goal !== 'string' || !input.goal.trim() || input.goal.length > 20000)) throw researchError('请输入工件路径,名称最多160字,研究目标最多20000字。', 400);
const id = randomUUID(), active = this.reserve(session, id), identity = { taskId: session.taskId, runId: session.runId };
active.promise = (async () => {
const file = await researchFileIdentity(input.path, { signal: active.signal }); active.signal.throwIfAborted();
if (session.taskId !== identity.taskId || session.runId !== identity.runId) throw researchError('登记期间任务已经切换,请重新登记。');
let task = this.store.core.task.get(session.taskId);
if (!task || ['completed', 'idle'].includes(task.status)) {
const goal = input.goal?.trim() ?? '静态研究登记工件 ' + (input.label?.trim() || path.basename(file.path)) + ' 的功能与代理机制,并以原Evidence为依据。';
const run = this.store.beginRun(session, goal, false, this.store.config);
run.engine = 'rea-stdio'; run.origin = 'user-research-registration';
this.store.message(session, 'user', goal); session.providerMessages.push({ role: 'user', content: goal });
session.status = 'paused'; this.store.finishRun(session, run, 'research_ready');
task = this.store.core.task.get(session.taskId);
if (session.title === '新任务') session.title = ('静态研究 · ' + (input.label?.trim() || path.basename(file.path))).slice(0, 28);
} else if (input.goal) task.instructions.push({ id: randomUUID(), content: input.goal.trim(), source: 'user-research-registration', createdAt: at() });
const run = this.store.owned('run', session.runId, session.id);
const target = { schemaVersion: 1, id: randomUUID(), sessionId: session.id, projectId: session.projectId,
taskId: task.id, runId: run.id, ...file, label: input.label?.trim() || path.basename(file.path),
source: 'user-registration', status: 'registered', registeredAt: at() };
const contract = this.store.artifactStore.write(session, run, researchTargetContract(target), { kind: 'research-target' });
this.store.core.artifact.set(contract.id, contract); target.contractArtifactId = contract.id; target.contractSha256 = contract.sha256;
return this.store.putRecord('research_target', session, target, 'research.target_registered');
})().finally(() => this.release(id, active));
return active.promise;
}
targets(session) { return [...this.store.core.research_target.values()].filter(target => target.sessionId === session.id && target.taskId === session.taskId).slice(-32); }
jobs(session) { return [...this.store.core.research_job.values()].filter(job => job.sessionId === session.id).slice(-30); }
targetFor(session, id) {
const target = this.store.owned('research_target', id, session.id);
if (target.taskId !== session.taskId) throw researchError('工件属于此前Task,请在当前任务重新登记。');
const artifact = this.store.owned('artifact', target.contractArtifactId, session.id);
if (artifact.kind !== 'research-target' || artifact.taskId !== target.taskId || artifact.sha256 !== target.contractSha256
|| this.store.artifactStore.read(artifact) !== JSON.stringify(researchTargetContract(target))) throw researchError('登记工件与封存身份不一致。');
return target;
}
start(session, targetId, operation, options = {}) {
const target = this.targetFor(session, targetId), spec = REA_OPERATIONS[operation];
if (!spec || !spec.extensions.includes(target.extension)) throw researchError('所选静态分析不适用于这个工件。', 400);
if (options.refresh && options.source === 'agent') throw researchError('重新执行分析需要用户从研究面板明确发起。');
const previous = this.jobs(session).filter(job => job.taskId === session.taskId && job.targetId === targetId && job.operationId === operation).at(-1);
if (previous && previous.status !== 'completed' && !options.refresh) throw researchError('此前分析没有可复用的完成Evidence,请查看原结果,再由用户选择重新分析。');
const id = randomUUID(), active = this.reserve(session, id, options), run = this.store.owned('run', session.runId, session.id);
const job = { schemaVersion: 1, id, sessionId: session.id, projectId: session.projectId, taskId: run.taskId, runId: run.id,
targetId, targetSha256: target.sha256, operationId: operation, operation: spec.name, status: 'queued', source: options.source ?? 'user',
startedAt: at(), finishedAt: null, requiresVerification: false, summary: '已登记分析范围,尚未调用REA。',
scope: 'static-artifact-analysis; no target execution', installation: this.availability() };
active.job = job;
const event = this.store.event(session, { kind: 'research', label: spec.label, tool: spec.name, phase: 'queued',
input: { targetId, path: target.path, sha256: target.sha256, operation } }); job.eventId = event.id;
try {
this.store.putRecord('research_job', session, job, 'research.queued');
active.promise = this.execute(session, target, job, run, active, options).finally(() => this.release(id, active));
active.promise.catch(() => {}); return { job, promise: active.promise };
} catch (error) { this.release(id, active); throw error; }
}
async execute(session, target, job, run, active, options) {
let adapter, returned = false;
const event = session.events.find(value => value.id === job.eventId);
const phase = (status, summary) => { job.status = status; job.summary = summary; event.phase = status; event.output = summary; this.store.save(session, { type: 'research.' + status, detail: { jobId: job.id } }); };
try {
job.before = await researchFileIdentity(target.path, { signal: active.signal }); active.signal.throwIfAborted();
if (job.before.sha256 !== target.sha256 || job.before.bytes !== target.bytes) throw researchError('工件在登记后变化,请按新版本重新登记。');
const reusable = !options.refresh && [...this.store.core.research_job.values()].findLast(value => value.id !== job.id && value.sessionId === session.id
&& value.taskId === job.taskId && value.targetId === target.id && value.operationId === job.operationId && value.status === 'completed' && value.evidenceBinding?.verified);
if (reusable) {
this.verifiedEvidence(session, reusable);
for (const key of ['evidence', 'bundle', 'raw', 'contractArtifactId', 'contractSha256', 'evidenceId', 'evidenceBinding', 'installation']) job[key] = structuredClone(reusable[key]);
job.reusedFromJobId = reusable.id; job.after = job.before; job.summary = '已复用原完整Evidence,登记工件SHA256仍一致;没有再次调用REA。';
} else {
const output = createResearchOutputDirectory(this.store.directory, job.id);
const scratch = output.path; job.outputDirectory = scratch; job.outputScope = output.scope;
adapter = this.adapterFactory(job.installation, { cwd: scratch, timeoutMs: this.timeoutMs,
onClient: client => { active.client = client; job.connection = { id: client.id, pid: client.pid ?? null, startedAt: client.startedAt }; this.store.save(session, { type: 'research.connection_owned', detail: { jobId: job.id } }); } });
phase('connecting', '正在核对REA握手和实际工具契约。');
const contract = await adapter.connect(active.signal);
const contractArtifact = this.store.artifactStore.write(session, run, contract, { kind: 'research-rea-contract' });
this.store.core.artifact.set(contractArtifact.id, contractArtifact); job.contractArtifactId = contractArtifact.id; job.contractSha256 = contractArtifact.sha256;
phase('analyzing', 'REA正在静态读取登记工件,完整原Evidence将独立封存。'); job.analysisDispatched = true;
const received = await adapter.analyze(target, job.operationId, { signal: active.signal }); returned = true;
const { bundleText, evidence, ...raw } = received;
job.raw = sealResearchDocument(this.store, session, run, JSON.stringify(raw), 'research-raw-response');
if (!evidence || !bundleText || received.result?.isError || received.exportResult?.isError) throw Object.assign(researchError('REA没有返回原完整Evidence;原响应已保留。'), { outcome: 'unverified' });
job.bundle = sealResearchDocument(this.store, session, run, bundleText, 'research-evidence-bundle');
job.evidence = sealResearchDocument(this.store, session, run, JSON.stringify(evidence), 'research-evidence');
job.evidenceBinding = bindReaEvidence({ structuredContent: evidence }, target, job.operation); job.evidenceId = evidence.evidence_id;
job.after = await researchFileIdentity(target.path, { signal: active.signal }); active.signal.throwIfAborted();
if (job.after.sha256 !== target.sha256 || job.after.bytes !== target.bytes) throw researchError('分析期间工件变化,原响应保留但不作为登记版本的已核验结果。');
job.summary = '原完整Evidence与登记工件、分析前后SHA256均已核对。静态候选和未知范围见原限制。';
}
const binding = this.store.artifactStore.write(session, run, jobContract(job), { kind: 'research-binding' });
this.store.core.artifact.set(binding.id, binding); job.bindingArtifactId = binding.id; job.bindingSha256 = binding.sha256;
job.status = 'completed';
} catch (error) {
job.errorCode = error.code ?? null; job.summary = this.redact(error.message ?? String(error));
job.status = active.signal.aborted ? 'cancelled' : error.outcome ?? (error.code && job.analysisDispatched && !returned ? 'unknown' : error.status === 409 ? 'stale' : 'failed');
job.requiresVerification = job.status === 'unknown'; job.evidenceBinding = null;
} finally {
if (adapter) {
try { job.cleanup = await adapter.close({ force: active.signal.aborted || !!job.errorCode }); }
catch (error) { job.cleanup = { rootExited: false, message: this.redact(error.message) }; }
const trace = { trace: active.client?.trace ?? [], stderr: this.redact(active.client?.stderr ?? ''), cleanup: job.cleanup };
const artifact = this.store.artifactStore.write(session, run, trace, { kind: 'research-transport' }); this.store.core.artifact.set(artifact.id, artifact); job.traceArtifactId = artifact.id;
if (!job.cleanup.rootExited) { job.status = 'unknown'; job.requiresVerification = true; job.evidenceBinding = null; job.summary += ' 所属REA进程关闭结果尚未确认。'; }
}
job.finishedAt = at(); event.phase = job.status; event.finishedAt = job.finishedAt; event.output = job.summary;
this.store.save(session, { type: 'research.result', detail: { jobId: job.id, status: job.status } });
}
return job;
}
verifiedEvidence(session, job) {
if (job.status !== 'completed' || !job.evidenceBinding?.verified || !job.bindingArtifactId) throw researchError('这个分析尚没有已核验的原完整Evidence。');
const binding = this.store.owned('artifact', job.bindingArtifactId, session.id);
if (binding.sha256 !== job.bindingSha256 || this.store.artifactStore.read(binding) !== JSON.stringify(jobContract(job))) throw researchError('研究结果与封存绑定不匹配。');
const target = this.store.owned('research_target', job.targetId, session.id);
const targetArtifact = this.store.owned('artifact', target.contractArtifactId, session.id);
if (targetArtifact.sha256 !== target.contractSha256 || this.store.artifactStore.read(targetArtifact) !== JSON.stringify(researchTargetContract(target)) || target.sha256 !== job.targetSha256) throw researchError('原研究工件身份与Evidence不匹配。');
const contract = this.store.owned('artifact', job.contractArtifactId, session.id);
if (contract.sha256 !== job.contractSha256) throw researchError('REA契约与封存引用不匹配。'); this.store.artifactStore.read(contract);
const evidence = JSON.parse(readResearchDocument(this.store, session, job.evidence)), bundle = JSON.parse(readResearchDocument(this.store, session, job.bundle));
const bound = bindReaEvidence({ structuredContent: evidence }, target, job.operation);
if (bound.evidenceId !== job.evidenceId || JSON.stringify(bound) !== JSON.stringify(job.evidenceBinding)
|| !bundle.records?.some(record => JSON.stringify(record) === JSON.stringify(evidence))) throw researchError('原完整Evidence不在封存的Bundle中。');
readResearchDocument(this.store, session, job.raw); return evidence;
}
readEvidence(session, jobId, { pointer = '/normalized_result', offset = 0, limit = 4000, maximumMessageBytes = 30000, callId = '' } = {}) {
const job = this.store.owned('research_job', jobId, session.id), evidence = this.verifiedEvidence(session, job), value = researchPointer(evidence, pointer);
const text = JSON.stringify(value, null, 2), viewSha256 = sha(text);
const metadata = { research_job_id: job.id, evidence_id: job.evidenceId, target_sha256: job.targetSha256,
pointer, view_sha256: viewSha256, source_artifact_id: job.evidence.id, source_document_sha256: job.evidence.documentSha256,
available_fields: value && typeof value === 'object' ? Object.keys(value).slice(0, 32) : [],
navigation: 'Use read_research_evidence with the same research_job_id and pointer, then next_offset.', scope: job.scope };
const frameBytes = object => Buffer.byteLength(JSON.stringify({ role: 'tool', tool_call_id: callId, content: JSON.stringify(object) }), 'utf8');
const reserve = frameBytes(metadata) + 128;
if (maximumMessageBytes - reserve < 1024) throw researchError('当前完整请求没有足够的Evidence页预算,请使用已返回摘要或缩小请求范围。');
const page = artifactPage({ id: job.evidence.id, sha256: viewSha256, kind: 'research-evidence-view' }, text, { offset, limit }, { maximumMessageBytes: maximumMessageBytes - reserve, callId });
delete page.artifact_id;
const result = { ...page, ...metadata, maximum_message_bytes: maximumMessageBytes };
if (frameBytes(result) > maximumMessageBytes) throw researchError('Evidence页超过当前完整协议预算,未返回超限页面。');
return result;
}
result(job) {
const summary = job.evidenceBinding?.summary ?? null, statistics = job.evidenceBinding?.statistics ?? null;
const summaryFits = Buffer.byteLength(JSON.stringify(summary), 'utf8') <= 2400;
return { status: job.status === 'completed' ? 'completed' : 'failed', research_status: job.status, research_job_id: job.id,
target_id: job.targetId, target_sha256: job.targetSha256, evidence_id: job.evidenceId ?? null, evidence_verified: !!job.evidenceBinding?.verified,
evidence_artifact_id: job.evidence?.id ?? null, bundle_artifact_id: job.bundle?.id ?? null, raw_artifact_id: job.raw?.id ?? null,
reused_from_job_id: job.reusedFromJobId ?? null, summary: summaryFits ? summary : null, summary_complete: summaryFits,
summary_excerpt: summaryFits ? null : JSON.stringify(summary).slice(0, 2400),
statistics: Buffer.byteLength(JSON.stringify(statistics), 'utf8') <= 1200 ? statistics : null,
limitations: (job.evidenceBinding?.limitations ?? []).slice(0, 12).map(value => value.slice(0, 280)),
limitations_complete: (job.evidenceBinding?.limitations ?? []).length <= 12 && (job.evidenceBinding?.limitations ?? []).every(value => value.length <= 280),
message: job.summary.slice(0, 1500), requires_review: job.requiresVerification, scope: job.scope };
}
originalDocument(session, job, kind = 'bundle') {
if (!['bundle', 'raw'].includes(kind) || !job[kind]) throw researchError('这个操作尚未保存所选原文。', 404);
if (kind === 'bundle') this.verifiedEvidence(session, job);
else if (job.reusedFromJobId) this.verifiedEvidence(session, job);
else {
const artifact = this.store.owned('artifact', job.raw.id, session.id);
if (artifact.taskId !== job.taskId || artifact.runId !== job.runId) throw researchError('原响应不属于这次研究运行。');
}
return readResearchDocument(this.store, session, job[kind]);
}
async stop(sessionId) {
const pending = [...this.active.values()].filter(value => value.sessionId === sessionId);
for (const active of pending) { if (active.job && RESEARCH_ACTIVE.has(active.job.status)) active.job.status = 'stopping'; active.controller.abort(new Error('用户停止了所属研究操作。')); }
await Promise.allSettled(pending.map(value => value.promise));
}
async stopAll() { await Promise.all([...new Set([...this.active.values()].map(value => value.sessionId))].map(id => this.stop(id))); }
}