207 lines
20 KiB
JavaScript
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))); }
|
|
}
|