@sanqianx/project-knowledge 4.7.0 → 5.0.0

package/_modules/knowledge-engine/src/coordinator.js

@@ -0,0 +1,263 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { EventEmitter } = require('node:events');
+const { RuntimeLayout, realpathWithMissingLeaf } = require('./runtime/layout');
+const AtomicFile = require('./runtime/atomic-file');
+const { ConversationStore } = require('./runtime/conversation-store');
+const { CommitReconciler } = require('./runtime/commit-reconciler');
+const { KnowledgePromotionService } = require('./runtime/knowledge-promotion');
+const { EngineRetrieval } = require('./retrieval');
+const { BridgeClient } = require('./bridge-client');
+const { HeadlessAnalyzer } = require('./headless-analyzer');
+const { MemoryService } = require('./memories');
+const { execGit } = require('./runtime/git-runner');
+
+class EngineCoordinator extends EventEmitter {
+  constructor(store, options = {}) {
+    super();
+    this.store = store;
+    this.layout = new RuntimeLayout(store.dataDir);
+    this.vectorUrl = options.vectorUrl || 'http://127.0.0.1:8787';
+    this.bridge = options.bridge || new BridgeClient(options.bridgeUrl);
+    this.consume = options.consume === true;
+    this.executionEnabled = options.managed !== true;
+    this.concurrency = Math.max(1, Math.min(2, Number(options.concurrency) || 2));
+    this.active = new Map();
+    this.jobs = new Set();
+    this.initializeHook = options.initializeHook;
+    this.profiles = new Map();
+    this.closed = false;
+    this.sharedIndexJobs = new Map();
+    this.sharedIndexDirty = new Set();
+    this.sharedIndexQueue = Promise.resolve();
+    this.memories = new MemoryService(store, { onMaterialized: scope => { this.indexSharedScope(scope).catch(() => {}); } });
+    this.projectStore = {
+      readConfig: id => { const p = store.getProject(id); if (!p) throw Object.assign(new Error('项目未登记。'), { code: 'PROJECT_NOT_FOUND' }); return { ...p, displayName: p.name, automation: { enabled: true } }; },
+      readState: id => store.readRuntime(id),
+      updateState: (id, fn) => store.updateRuntime(id, fn),
+      readRequirements: () => [],
+    };
+    const registryStore = { listIds: () => store.listProjects().map(p => p.projectId), readDisplaySnapshot: id => store.getProject(id) };
+    this.retrieval = new EngineRetrieval({ layout: this.layout, projectStore: this.projectStore, registryStore, store, memories: this.memories, vectorUrl: this.vectorUrl });
+    this.conversations = new ConversationStore({ layout: this.layout, projectStore: this.projectStore });
+    this.analyzer = options.analyzer || new HeadlessAnalyzer({ resolveProfile: id => this.profiles.get(id) || this.profiles.get('default'), timeoutMs: options.timeoutMs });
+    this.promotion = new KnowledgePromotionService({ layout: this.layout, projectStore: this.projectStore, analyzer: { runClaim: async input => {
+      const run = this.currentRun(input.projectId);
+      store.updateRun(run.runId, { analysisRunId: input.claim.runId, phase: 'analyzing' });
+      this.notify(run, '正在分析冻结的提交证据');
+      if (run.debugFailure) throw Object.assign(new Error('调试模式：模拟分析失败。'), { code: 'DEBUG_SIMULATED_FAILURE', retryable: true });
+      await this.analyzer.runClaim(input);
+      store.updateRun(run.runId, { phase: 'promoting' });
+      this.notify(run, '校验并晋升知识');
+      return { ok: true };
+    } } });
+    this.reconciler = new CommitReconciler({ layout: this.layout, projectStore: this.projectStore, registryStore, conversationStore: this.conversations, retrievalService: this.retrieval, claimProcessor: this.promotion });
+    this.ready = this.initialize();
+  }
+  currentRun(id) { return this.store.getRun(this.active.get(id)); }
+  setProfile(id, profile) { if (profile) this.profiles.set(id, profile); else this.profiles.delete(id); }
+  notify(run, summary) {
+    const event = this.store.addEvent({ type: 'knowledge.run', projectId: run.projectId, runId: run.runId, commitSha: run.commitSha, phase: run.phase, summary });
+    this.emit('progress', event);
+  }
+  async initialize() {
+    await this.initializeHook?.();
+    if (this.executionEnabled) await this.promotion.recoverAll();
+    await this.memories.recover();
+    for (const run of this.store.state.runs) {
+      if (run.state === 'running') this.store.updateRun(run.runId, { state: 'queued', phase: 'recovering' });
+    }
+    if (this.consume) {
+      await this.drain().catch(() => {});
+      this.poll = setInterval(() => this.drain().catch(() => {}), 2000);
+      this.poll.unref();
+    }
+    this.pump();
+    if (this.executionEnabled) for (const run of this.store.state.runs.filter(r => r.state === 'index-pending')) this.retry(run.runId);
+  }
+  async activate() {
+    await this.ready;
+    if (this.executionEnabled && this.consume) return;
+    await this.promotion.recoverAll();
+    this.executionEnabled = true;
+    this.consume = true;
+    await this.drain();
+    if (!this.poll) { this.poll = setInterval(() => this.drain(), 2000); this.poll.unref(); }
+    for (const run of this.store.state.runs.filter(r => r.state === 'index-pending')) this.retry(run.runId);
+    this.pump();
+  }
+  enqueue(input) {
+    const p = this.store.getProject(input.projectId);
+    if (!p || p.enabled === false) throw Object.assign(new Error('项目未登记或已停用。'), { code: 'PROJECT_NOT_FOUND', status: 404 });
+    const run = this.store.addRun(input);
+    if (input.debugFailure) this.store.updateRun(run.runId, { debugFailure: true });
+    this.emit('progress', { projectId: run.projectId, runId: run.runId, commitSha: run.commitSha, phase: run.phase });
+    this.ready.then(() => this.pump());
+    return run;
+  }
+  async removeProject(projectId) {
+    await this.ready;
+    // An indexing job can still hold a write lease even after its state changes.
+    if (this.active.has(projectId)) throw Object.assign(new Error('此项目正在执行知识维护，请等待写入结束后再解绑。'), { status: 409, code: 'PROJECT_BUSY' });
+    const result = this.store.removeProject(projectId);
+    if (result.removed) this.emit('progress', this.store.addEvent({ type: 'project.unregister', projectId, summary: `已解绑项目，取消 ${result.cancelledRuns} 个未开始任务；知识与提交证据保留。` }));
+    return result;
+  }
+  drain() {
+    if (this.drainJob) return this.drainJob;
+    if (this.closed) return Promise.resolve();
+    const job = this.drainJournals().finally(() => { this.drainJob = null; });
+    this.drainJob = job;
+    return job;
+  }
+  async drainJournals() {
+    this.draining = true;
+    try {
+      await this.bridge.registerConsumer('knowledge-engine', { journals: ['*'] });
+      for (const journal of await this.bridge.listJournals()) {
+        if (this.closed) break;
+        const cursor = this.store.state.journalCursors[journal.journalId] || 0;
+        const events = await this.bridge.readEvents({ journalId: journal.journalId, fromSequence: cursor + 1, limit: 100 });
+        let through = cursor;
+        for (const event of events) {
+          if (this.closed) break;
+          const p = this.store.listProjects().find(p => p.enabled !== false && ((journal.journalId !== 'global' && p.journalId === journal.journalId)
+            || ((journal.journalId === 'global' || !p.journalId) && event.repoIdentity?.workspaceRoot && this.layout.pathsEqual(p.repoPath, event.repoIdentity.workspaceRoot))));
+          if (p) {
+            if (event.schema === 'ai-coding-event/v1' && ['user_prompt', 'assistant_response'].includes(event.eventType)) await this.conversations.appendBridgeEvent(p.projectId, { ...event, journalId: journal.journalId });
+            if (event.schema === 'git-commit-boundary/v1' && /^[a-f0-9]{7,64}$/i.test(event.commitSha || '')) {
+              if (!fs.existsSync(this.layout.getProjectCommitBoundaryPath(p.projectId, event.commitSha))) this.conversations.writeBoundary(p.projectId, { ...event, journalId: journal.journalId, parentShas: event.parents || [], bridgeCursorAtCommit: event.sequence, journalSequence: event.sequence, operationId: event.operationId || `bridge-${journal.journalId}-${event.sequence}`, committedAt: event.committedAt || event.capturedAt });
+              const baseline = p.runtime.lastAnalyzedCommit || p.trackingStartCommit;
+              const completed = this.reconciler.processingLedger.read(p.projectId, event.commitSha);
+              const historical = baseline && (baseline === event.commitSha || (await execGit(p.repoPath, ['merge-base', '--is-ancestor', event.commitSha, baseline])).ok);
+              if (!completed && !historical && this.store.getProject(p.projectId)?.enabled) this.enqueue({ projectId: p.projectId, commitSha: event.commitSha, trigger: 'git-hook', journalId: journal.journalId, journalSequence: event.sequence });
+            }
+          }
+          through = event.sequence;
+        }
+        // All evidence projections and queued jobs are durable before ACK.
+        if (through > cursor) this.store.setJournalCursor(journal.journalId, through);
+        await this.bridge.ackConsumerCursor('knowledge-engine', through, { journalId: journal.journalId });
+      }
+      this.journalError = null;
+    } catch { this.journalError = '事件日志连接异常，已保留游标并等待恢复。'; }
+    finally { this.draining = false; }
+  }
+  pump() {
+    if (this.closed || !this.executionEnabled) return;
+    const queued = this.store.state.runs.filter(r => r.state === 'queued').sort((a, b) => a.sequence - b.sequence);
+    for (const run of queued) {
+      if (this.active.size >= this.concurrency) break;
+      if (this.active.has(run.projectId)) continue;
+      if (this.store.state.runs.some(previous => previous.projectId === run.projectId && previous.sequence < run.sequence && previous.state === 'failed' && !previous.promotedAt)) {
+        if (run.phase !== 'waiting-previous') { this.store.updateRun(run.runId, { phase: 'waiting-previous' }); this.notify(run, '等待前一条失败提交恢复，其他项目继续运行'); }
+        continue;
+      }
+      this.active.set(run.projectId, run.runId);
+      const job = this.execute(run).catch(() => { this.closed = true; this.journalError = '持久化失败，已停止维护，请检查数据目录。'; }).finally(() => { this.active.delete(run.projectId); this.jobs.delete(job); this.pump(); });
+      this.jobs.add(job);
+    }
+  }
+  async execute(run) {
+    if (run.promotedAt) { await this.index(run); return; }
+    this.store.updateRun(run.runId, { state: 'running', phase: 'preparing' });
+    this.notify(run, '准备提交证据');
+    try {
+      const project = this.store.getProject(run.projectId);
+      const canonicalPath = realpathWithMissingLeaf(project.knowledgePath);
+      const targetKey = crypto.createHash('sha256').update(process.platform === 'win32' ? canonicalPath.toLowerCase() : canonicalPath).digest('hex');
+      const result = await AtomicFile.withFileLock(this.layout.getRuntimePath('locks', `${targetKey}.lock`), async () => {
+        const state = this.store.readRuntime(run.projectId);
+        if (state.lastAnalyzedCommit === run.commitSha) return { ok: true, recovered: true };
+        return this.reconciler.processCommitEvent({ projectId: run.projectId, commitSha: run.commitSha, operationId: run.runId });
+      }, { timeoutMs: 15 * 60 * 1000 });
+      if (!result.ok) throw Object.assign(new Error(result.error?.message || '知识维护失败。'), result.error);
+      const claimRunId = result.runId || run.analysisRunId;
+      let staging = null;
+      if (claimRunId && fs.existsSync(this.promotion.manifestPath(run.projectId, claimRunId))) staging = this.promotion.readManifest(run.projectId, claimRunId);
+      this.store.updateRun(run.runId, { phase: 'promoted', promotedAt: new Date().toISOString(), staging });
+      this.memories.capture(run);
+      this.notify(run, '知识已晋升，正在更新索引');
+      await this.index(run);
+    } catch (error) {
+      const message = error.code === 'AI_PROFILE_REQUIRED' ? '请配置后台默认模型。' : error.code === 'ANALYSIS_OUTPUT_MISSING' ? 'Agent 未生成知识维护文件，证据与原知识已保留，可重试。' : '知识维护失败，证据与原知识已保留。';
+      this.store.updateRun(run.runId, { state: 'failed', phase: 'failed', finishedAt: new Date().toISOString(), error: { code: error.code || 'ANALYSIS_FAILED', message, retryable: error.retryable === true } });
+      this.notify(run, '知识维护失败');
+    }
+  }
+  async index(run) {
+    const project = this.store.getProject(run.projectId);
+    try {
+      this.store.updateRun(run.runId, { phase: 'indexing', indexState: 'running' });
+      const response = await fetch(new URL('/api/sync', this.vectorUrl), { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ project: project.vectorProjectId || project.projectId, sourceDir: project.knowledgePath }), signal: AbortSignal.timeout(120000) });
+      const payload = await response.json();
+      if (!response.ok || payload.ok !== true) throw new Error('INDEX_FAILED');
+      await this.store.updateRuntime(run.projectId, state => { state.index.dirty = false; state.index.status = 'ready'; });
+      this.store.updateRun(run.runId, { state: 'succeeded', phase: 'ready', indexState: 'succeeded', error: null, finishedAt: new Date().toISOString() });
+      this.notify(run, '知识已更新并可检索');
+    } catch {
+      this.store.updateRun(run.runId, { state: 'index-pending', phase: 'index-pending', indexState: 'failed', finishedAt: new Date().toISOString(), error: { code: 'INDEX_FAILED', message: '知识已更新，索引待修复。', retryable: true } });
+      this.notify(run, '知识已更新，索引待修复');
+    }
+  }
+  syncSharedIndexes() { for (const scope of this.store.state.sharedScopes) this.indexSharedScope(scope).catch(() => {}); }
+  async indexSharedScope(scope) {
+    if (this.closed) return;
+    if (this.sharedIndexJobs.has(scope.id)) { this.sharedIndexDirty.add(scope.id); return this.sharedIndexJobs.get(scope.id); }
+    // Shared updates are small but may be numerous; serialize imports rather
+    // than burst model requests for every domain after startup.
+    const job = this.sharedIndexQueue.catch(() => {}).then(async () => {
+      if (this.closed || !this.store.state.sharedScopes.some(s => s.id === scope.id)) return;
+      let index;
+      try {
+        const files = require('./runtime/markdown-knowledge-indexer').listMarkdownFiles(scope.knowledgePath);
+        const digest = crypto.createHash('sha256');
+        for (const file of files.sort()) {
+          if (!this.layout.isPathInside(scope.knowledgePath, file, { realpath: true })) continue;
+          digest.update(path.relative(scope.knowledgePath, file)).update('\0').update(fs.readFileSync(file));
+        }
+        const fingerprint = digest.digest('hex');
+        const current = this.store.state.sharedScopes.find(s => s.id === scope.id);
+        if (!current) return;
+        if (current.index?.status === 'ready' && current.index.fingerprint === fingerprint) {
+          const health = await fetch(new URL('/api/projects', this.vectorUrl), { signal: AbortSignal.timeout(8000) });
+          const payload = await health.json();
+          if (health.ok && payload.projects?.some(p => p.name === `scope-${scope.kind}-${scope.id}` && p.hasIndex && this.layout.pathsEqual(p.sourceDir || '', scope.knowledgePath))) return;
+        }
+        const response = await fetch(new URL('/api/import', this.vectorUrl), { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ projectName: `scope-${scope.kind}-${scope.id}`, sourceDir: scope.knowledgePath, watch: false }), signal: AbortSignal.timeout(120000) });
+        const payload = await response.json();
+        if (!response.ok || payload.ok !== true) throw new Error('INDEX_FAILED');
+        index = { status: 'ready', fingerprint, updatedAt: new Date().toISOString() };
+      } catch { index = { status: 'pending', message: '共享知识已保存，索引待恢复。' }; }
+      // Configuration can replace projection objects while the import awaits.
+      const current = this.store.state.sharedScopes.find(s => s.id === scope.id);
+      if (!current) return;
+      const changed = current.index?.status !== index.status || current.index?.fingerprint !== index.fingerprint;
+      current.index = index;
+      this.store.save();
+      if (changed) this.emit('progress', this.store.addEvent({ type: 'scope.index', brainId: scope.brainId, scopeId: scope.id, summary: current.index.status === 'ready' ? '共享知识索引已更新' : current.index.message }));
+    }).finally(() => { this.sharedIndexJobs.delete(scope.id); if (this.sharedIndexDirty.delete(scope.id) && !this.closed) this.indexSharedScope(scope).catch(() => {}); });
+    this.sharedIndexQueue = job;
+    this.sharedIndexJobs.set(scope.id, job); return job;
+  }
+  retry(id) {
+    const run = this.store.getRun(id);
+    if (!run || !['failed', 'index-pending'].includes(run.state)) throw Object.assign(new Error('只有失败或索引待修复的运行可以重试。'), { status: 409 });
+    this.store.updateRun(id, { state: 'queued', phase: run.promotedAt ? 'index-pending' : 'queued', finishedAt: null, error: null, debugFailure: false });
+    this.pump();
+    return run;
+  }
+  async close() {
+    this.closed = true; clearInterval(this.poll);
+    this.bridge.close?.();
+    await this.analyzer.close?.();
+    // A consumer may still be persisting evidence or an ACK. Keep the writer
+    // lease until that work settles; the next process must never overlap it.
+    await Promise.all([this.drainJob, ...this.jobs, ...this.sharedIndexJobs.values()]);
+    this.removeAllListeners(); this.profiles.clear();
+  }
+}
+
+module.exports = { EngineCoordinator };

package/_modules/knowledge-engine/src/headless-analyzer.js

@@ -0,0 +1,75 @@
+'use strict';
+const { fork, execFile } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const AtomicFile = require('./runtime/atomic-file');
+const { canonicalRelativePath } = require('./runtime/knowledge-promotion');
+const { RuntimeLayout } = require('./runtime/layout');
+const { frameFrozenEvidence, requireAnalysisOutput } = require('./analysis-contract');
+
+class HeadlessAnalyzer {
+  constructor({ resolveProfile, timeoutMs = 15 * 60 * 1000, workerPath = path.join(__dirname, 'analysis-worker.js') } = {}) { this.resolveProfile = resolveProfile; this.timeoutMs = timeoutMs; this.workerPath = workerPath; this.children = new Map(); this.closed = false; }
+  async runClaim(input) {
+    if (this.closed) throw Object.assign(new Error('分析服务正在关闭。'), { code: 'WORKER_STOPPED', retryable: true });
+    const profile = this.resolveProfile && await this.resolveProfile(input.projectId);
+    if (!profile || !profile.apiKey || !(profile.mainModel || profile.models?.default)) throw Object.assign(new Error('请先在工作台配置后台维护的默认模型。'), { code: 'AI_PROFILE_REQUIRED', status: 503, retryable: true });
+    const refs = [`commit:${input.claim.commitSha}`, `patch:${input.claim.patchHash}`, `conversation:${input.claim.conversationSnapshotHash}`, `retrieval:${input.claim.retrievalManifestHash}`];
+    const contract = `\n\nOUTPUT CONTRACT\nRead frozen evidence only beneath ${input.evidenceRoot}. Write only beneath ${input.stagingPath}. Put Markdown under files/<allowed-path> (README.md, GOAL.md, ARCHITECTURE.md, modules/*.md, changes/*.md). Write ${input.manifestPath} with schema knowledge-staging-manifest/v1, projectId ${input.projectId}, runId ${input.claim.runId}, commitSha ${input.claim.commitSha}, and non-empty operations. Each operation needs path, operation (create/replace/delete), reason, and evidenceReferences ${JSON.stringify(refs)}. Omit sha256: the engine seals staged bytes itself. Do not modify code, final knowledge, other runs, or indexes. Do not invent intent if conversations are unavailable.`;
+    const pathContract = `\nPATH CONTRACT (mandatory): operations[].path is the FINAL knowledge-relative POSIX path, NEVER a staging path and NEVER prefixed with "files/". Example: write the physical file ${path.join(input.stagingPath, 'files', 'changes', `${input.claim.commitSha.slice(0, 12)}.md`)} but put "path": "changes/${input.claim.commitSha.slice(0, 12)}.md" in manifest.json. Use forward slashes even on Windows. Minimal manifest shape: ${JSON.stringify({ schema: 'knowledge-staging-manifest/v1', projectId: input.projectId, runId: input.claim.runId, commitSha: input.claim.commitSha, operations: [{ path: `changes/${input.claim.commitSha.slice(0, 12)}.md`, operation: 'create', reason: 'Describe the evidence-backed change', evidenceReferences: refs }] })}`;
+    await new Promise((resolve, reject) => {
+      const env = { ...process.env };
+      delete env.CLAUDECODE;
+      const child = fork(this.workerPath, [], { cwd: input.stagingPath, env, execArgv: [], detached: process.platform !== 'win32', windowsHide: true, stdio: ['ignore', 'ignore', 'ignore', 'ipc'] });
+      let requested = false, outcome, escalation, termination = Promise.resolve();
+      let exited;
+      const completion = new Promise(done => { exited = done; });
+      const stop = error => {
+        if (requested) return;
+        requested = true;
+        outcome = error;
+        clearTimeout(timer);
+        if (child.connected) child.send({ type: 'cancel' }, () => {});
+        escalation = setTimeout(() => {
+          // Windows SIGTERM kills the worker without allowing SDK cleanup.
+          // Abort cooperatively first; escalation must kill its whole tree.
+          if (process.platform === 'win32') termination = new Promise(done => execFile('taskkill', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true }, () => done()));
+          else { try { process.kill(-child.pid, 'SIGKILL'); } catch { child.kill('SIGKILL'); } }
+        }, 2000);
+        escalation.unref();
+      };
+      this.children.set(child, { stop, completion });
+      const timer = setTimeout(() => stop(Object.assign(new Error('知识分析超时。'), { code: 'MODEL_TIMEOUT', retryable: true })), this.timeoutMs);
+      child.on('message', message => {
+        if (message?.type === 'complete') stop();
+        else if (message?.type === 'failure') stop(Object.assign(new Error('后台 Agent 分析失败，请检查模型配置。'), { code: ['AI_RUNTIME_REQUIRED', 'ANALYSIS_OUTPUT_MISSING'].includes(message.code) ? message.code : 'MODEL_FAILED', retryable: true }));
+      });
+      child.on('error', () => stop(Object.assign(new Error('无法启动后台分析进程。'), { code: 'WORKER_START_FAILED', retryable: true })));
+      // A completion message is not an exit: retain the directory lock until
+      // the worker has actually stopped writing, including timeout/shutdown.
+      child.on('close', async () => {
+        clearTimeout(timer); clearTimeout(escalation); await termination; this.children.delete(child); exited();
+        if (!requested) outcome = Object.assign(new Error('后台分析进程意外退出。'), { code: 'WORKER_EXITED', retryable: true });
+        if (outcome) reject(outcome); else resolve();
+      });
+      const memoryContract = '\nYou may optionally include memoryCandidates in manifest.json: [{text, entryId, quote}]. Only suggest durable user preferences explicitly evidenced in a promoted document; quote must be an exact excerpt (at least 8 characters) from that document. Never infer preferences from code style alone. These stay unconfirmed until the user accepts them.';
+      const languageContract = input.config?.knowledgeLanguage === 'en-US' ? '\nOUTPUT LANGUAGE: English. Preserve identifiers and verbatim evidence quotations.' : '\n输出语言：简体中文。知识正文、operations[].reason 与候选记忆用简体中文；代码标识、路径、哈希和原文证据引用保持不变。';
+      child.send({ profile, prompt: `${frameFrozenEvidence(input.prompt)}${contract}${pathContract}${memoryContract}${languageContract}`, manifestPath: input.manifestPath, stagingPath: input.stagingPath, safetyPolicy: input.safetyPolicy }, error => { if (error) stop(Object.assign(new Error('无法发送分析任务。'), { code: 'WORKER_START_FAILED', retryable: true })); });
+    });
+    requireAnalysisOutput(input.manifestPath);
+    const manifest = AtomicFile.readJsonStrict(input.manifestPath);
+    const layout = new RuntimeLayout(input.stagingPath);
+    for (const operation of manifest.operations || []) {
+      if (operation.operation === 'delete' || operation.sha256 != null) continue;
+      const relative = canonicalRelativePath(operation.path);
+      const file = path.join(input.stagingPath, 'files', ...relative.split('/'));
+      if (!layout.isPathInside(input.stagingPath, file, { realpath: true }) || fs.lstatSync(file).isSymbolicLink()) throw Object.assign(new Error('分析产物越界。'), { code: 'PATH_OUTSIDE_ROOT' });
+      operation.sha256 = `sha256:${crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex')}`;
+    }
+    AtomicFile.writeJsonAtomic(input.manifestPath, manifest);
+    return { ok: true };
+  }
+  async close() { this.closed = true; const running = [...this.children.values()]; for (const job of running) job.stop(Object.assign(new Error('分析服务正在关闭。'), { code: 'WORKER_STOPPED', retryable: true })); await Promise.all(running.map(job => job.completion)); }
+}
+
+module.exports = { HeadlessAnalyzer };

package/_modules/knowledge-engine/src/memories.js

@@ -0,0 +1,85 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const AtomicFile = require('./runtime/atomic-file');
+const { RuntimeLayout } = require('./runtime/layout');
+const { validateProjectId, DomainError } = require('./runtime/contracts');
+
+class MemoryService {
+  constructor(store, options = {}) { this.store = store; this.layout = new RuntimeLayout(store.dataDir); this.onMaterialized = options.onMaterialized; }
+  async configure(scopes) {
+    if (!Array.isArray(scopes)) throw new DomainError('INVALID_ARGUMENT', '共享范围必须是数组。');
+    const ids = new Set();
+    const projected = scopes.map(scope => {
+      validateProjectId(scope.id); validateProjectId(scope.brainId);
+      if (scope.domainId) validateProjectId(scope.domainId);
+      if (ids.has(scope.id) || !['brain', 'domain'].includes(scope.kind) || !path.isAbsolute(scope.knowledgePath || '')) throw new DomainError('INVALID_ARGUMENT', '共享范围绑定无效。');
+      ids.add(scope.id);
+      const index = this.store.state.sharedScopes.find(s => s.id === scope.id)?.index;
+      return { id: scope.id, kind: scope.kind, brainId: scope.brainId, domainId: scope.domainId || null, name: String(scope.name || scope.id), knowledgePath: path.resolve(scope.knowledgePath), ...(index ? { index } : {}) };
+    });
+    const overlaps = (a, b) => this.layout.isPathInside(a, b, { realpath: true }) || this.layout.isPathInside(b, a, { realpath: true });
+    for (const scope of projected) {
+      if (this.store.listProjects().some(p => overlaps(p.knowledgePath, scope.knowledgePath) || overlaps(p.repoPath, scope.knowledgePath)) || projected.some(s => s.id !== scope.id && overlaps(s.knowledgePath, scope.knowledgePath))) throw new DomainError('PATH_OUTSIDE_ROOT', '共享目录与其他知识或代码目录冲突。', { status: 409 });
+      const prior = this.store.state.sharedScopes.find(s => s.id === scope.id);
+      if (prior && !this.layout.pathsEqual(prior.knowledgePath, scope.knowledgePath)) throw new DomainError('IMMUTABLE_FIELD', '共享目录已绑定，不能隐式移动知识。', { status: 409 });
+    }
+    // The shell remains the registry owner; this is a whitelisted projection.
+    this.store.state.sharedScopes = projected; this.store.save();
+    for (const scope of projected) fs.mkdirSync(scope.knowledgePath, { recursive: true });
+    await this.recover();
+    return projected;
+  }
+  list({ brainId, status } = {}) { return this.store.state.memories.filter(m => (!brainId || m.brainId === brainId) && (!status || m.status === status)); }
+  capture(run) {
+    const project = this.store.getProject(run.projectId);
+    if (!project || !run.promotedAt) return;
+    const candidates = Array.isArray(run.staging?.memoryCandidates) ? run.staging.memoryCandidates : [];
+    for (const raw of candidates.slice(0, 20)) {
+      if (!raw || typeof raw !== 'object') continue;
+      const text = String(raw.text || '').trim();
+      const quote = String(raw.quote || '').trim();
+      const entryId = String(raw.entryId || '');
+      const file = path.resolve(project.knowledgePath, entryId);
+      if (!text || text.length > 2000 || quote.length < 8 || !run.staging.operations?.some(op => op.operation !== 'delete' && op.path === entryId) || !this.layout.isPathInside(project.knowledgePath, file, { realpath: true }) || !fs.existsSync(file) || !fs.readFileSync(file, 'utf8').includes(quote)) continue;
+      const fingerprint = crypto.createHash('sha256').update(`${project.brainId || 'brain-default'}:${text.toLowerCase().replace(/\s+/g, ' ')}`).digest('hex');
+      if (this.store.state.memories.some(m => m.fingerprint === fingerprint)) continue;
+      this.store.state.memories.push({ id: `memory-${crypto.randomUUID()}`, fingerprint, brainId: project.brainId || 'brain-default', domainId: project.domainId || null, text, status: 'candidate', evidence: { projectId: project.projectId, commitSha: run.commitSha, runId: run.runId, entryId, quote }, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() });
+    }
+    this.store.save();
+  }
+  async update(id, input) {
+    return AtomicFile.withFileLock(this.layout.getRuntimePath('locks', 'memories.lock'), async () => {
+      const memory = this.store.state.memories.find(m => m.id === id);
+      if (!memory) throw new DomainError('PROJECT_NOT_FOUND', '记忆不存在。', { status: 404 });
+      if (input.text !== undefined && (typeof input.text !== 'string' || !input.text.trim() || input.text.length > 2000)) throw new DomainError('INVALID_ARGUMENT', '记忆内容必须为 1–2000 个字符。');
+      if (input.status !== undefined && !['confirmed', 'ignored'].includes(input.status)) throw new DomainError('INVALID_ARGUMENT', '记忆状态无效。');
+      if (memory.status === 'ignored') throw new DomainError('INVALID_ARGUMENT', '该候选已忽略。', { status: 409 });
+      if (input.status === 'confirmed' && !this.store.state.sharedScopes.some(s => s.kind === 'brain' && s.brainId === memory.brainId)) throw new DomainError('INVALID_ARGUMENT', '请先绑定智脑共享目录。', { status: 409 });
+      Object.assign(memory, { text: input.text?.trim() || memory.text, status: input.status || memory.status, updatedAt: new Date().toISOString() });
+      // Persist confirmation before writing. Retrieval verifies the materialized
+      // file against this state, so a crash cannot inject unconfirmed content.
+      this.store.save();
+      await this.recover();
+      return memory;
+    });
+  }
+  content(brainId) {
+    return '# 已确认的长期记忆\n\n' + this.list({ brainId, status: 'confirmed' }).map(m => `## ${m.id}\n\n${m.text}\n\n来源：${m.evidence.projectId} · ${m.evidence.commitSha} · ${m.evidence.entryId}\n`).join('\n');
+  }
+  file(scope) { return path.join(scope.knowledgePath, 'memories', 'confirmed.md'); }
+  async recover() {
+    for (const scope of this.store.state.sharedScopes.filter(s => s.kind === 'brain')) {
+      const file = this.file(scope);
+      if (!this.layout.isPathInside(scope.knowledgePath, file, { realpath: true }) || fs.existsSync(file) && fs.lstatSync(file).isSymbolicLink()) throw new DomainError('PATH_OUTSIDE_ROOT', '记忆文件目录越界。', { status: 403 });
+      const content = this.content(scope.brainId);
+      if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== content) {
+        AtomicFile.writeFileAtomic(file, content);
+        await this.onMaterialized?.(scope);
+      }
+    }
+  }
+  validFile(scope) { const file = this.file(scope); return fs.existsSync(file) && fs.readFileSync(file, 'utf8') === this.content(scope.brainId); }
+}
+module.exports = { MemoryService };

package/_modules/knowledge-engine/src/retrieval.js

@@ -0,0 +1,116 @@
+'use strict';
+const fs = require('node:fs');
+const path = require('node:path');
+const { KnowledgeRetrievalService } = require('./runtime/knowledge-retrieval-service');
+const { listMarkdownFiles } = require('./runtime/markdown-knowledge-indexer');
+const { DomainError } = require('./runtime/contracts');
+
+class EngineRetrieval extends KnowledgeRetrievalService {
+  constructor(options) { super(options); this.store = options.store; this.memories = options.memories; this.vectorUrl = options.vectorUrl || 'http://127.0.0.1:8787'; }
+  resolve(input = {}) {
+    let project = this.store.getProject(input.projectId || input.projectSlug || input.project);
+    if (!project && (input.repoPath || input.path)) project = this.store.listProjects().find(p => this.layout.pathsEqual(p.repoPath, input.repoPath || input.path));
+    if (!project || project.enabled === false) throw new DomainError('PROJECT_NOT_FOUND', '项目尚未登记。', { status: 404 });
+    return project;
+  }
+  project(input = {}) {
+    if (input.project && input.project.projectId) return input.project;
+    const p = this.resolve(input);
+    return { projectId: p.projectId, projectSlug: p.projectId, primarySpaceId: `project:${p.projectId}`, knowledgePath: p.knowledgePath, relatedProjectIds: p.relatedProjectIds || [], index: this.store.readRuntime(p.projectId).index };
+  }
+  scopes(project) {
+    const registration = this.store.getProject(project.projectId);
+    return [...super.scopes(project), ...this.sharedScopes(registration, 'domain')];
+  }
+  sharedScopes(registration, range) {
+    return this.store.state.sharedScopes.filter(s => s.brainId === registration.brainId && (s.kind === 'brain' || range === 'brain' || s.domainId === registration.domainId)).map(s => ({ projectId: s.id, spaceId: `${s.kind}:${s.id}`, knowledgePath: s.knowledgePath, weight: s.kind === 'brain' ? 0.6 : 0.75, reason: s.kind }));
+  }
+  scanCurrent(scopes) {
+    const ordinary = scopes.filter(s => this.store.getProject(s.projectId));
+    const shared = scopes.filter(s => !this.store.getProject(s.projectId));
+    const result = super.scanCurrent(ordinary);
+    if (!shared.length) return result;
+    const scanner = new KnowledgeRetrievalService({ layout: this.layout, projectStore: { readState: () => ({ index: {} }) } });
+    const extra = scanner.scanCurrent(shared);
+    for (const [id, candidate] of extra.candidates) {
+      const scope = this.store.state.sharedScopes.find(s => s.id === candidate.projectId);
+      if (candidate.entryId.startsWith('memories/') && (scope.kind !== 'brain' || candidate.entryId !== 'memories/confirmed.md' || !this.memories?.validFile(scope))) continue;
+      result.candidates.set(id, candidate);
+    }
+    result.scopeHealth.push(...extra.scopeHealth);
+    return result;
+  }
+  async recallIndex(scopes, query, current, health) {
+    if (!query) { health.index = 'unavailable'; return; }
+    const mappings = scopes.map(s => ({ scope: s, registration: this.store.getProject(s.projectId) || (() => { const shared = this.store.state.sharedScopes.find(p => p.id === s.projectId); return shared ? { vectorProjectId: `scope-${shared.kind}-${shared.id}` } : null; })() })).filter(m => m.registration);
+    try {
+      const url = new URL('/api/search', this.vectorUrl);
+      url.searchParams.set('q', query);
+      url.searchParams.set('projects', mappings.map(m => m.registration.vectorProjectId || m.scope.projectId).join(','));
+      url.searchParams.set('maxResults', String(this.candidateLimit));
+      const response = await fetch(url, { signal: AbortSignal.timeout(8000) });
+      if (!response.ok) throw new Error('VECTOR_UNAVAILABLE');
+      const payload = await response.json();
+      if (payload.errors && payload.errors.length) throw new Error('VECTOR_QUERY_FAILED');
+      // Vectors only contribute a rank. Displayed text/hash always comes from
+      // current canonical files, so deleted or stale index bodies cannot leak.
+      for (const row of payload.results || []) {
+        const mapping = mappings.find(m => (m.registration.vectorProjectId || m.scope.projectId) === row.project);
+        if (!mapping) continue;
+        const uri = row.uri || row.documentUri || '';
+        const entry = path.isAbsolute(uri) ? path.relative(mapping.scope.knowledgePath, uri).replace(/\\/g, '/') : String(uri).replace(/\\/g, '/');
+        for (const candidate of current.values()) {
+          if (candidate.spaceId === mapping.scope.spaceId && candidate.entryId === entry) {
+            candidate.indexScore = Math.max(candidate.indexScore || 0, Math.max(0, Number(row.score) || 0));
+            candidate.indexChannels = ['vector-hub'];
+          }
+        }
+      }
+      health.index = payload.projectsSkipped?.length ? 'partial' : 'ok';
+    } catch { health.index = 'degraded'; health.reason = 'vector-hub-unavailable'; }
+  }
+  async search(input = {}) {
+    const registration = this.resolve(input);
+    const project = this.project({ projectId: registration.projectId });
+    let scopes = [{ projectId: project.projectId, spaceId: project.primarySpaceId, knowledgePath: project.knowledgePath, weight: 1, reason: 'primary' }];
+    if (input.scope === 'domain' || input.scope === 'brain') {
+      scopes = this.store.listProjects().filter(p => p.enabled !== false && p.brainId === registration.brainId
+        && (input.scope === 'brain' || p.domainId === registration.domainId)).map(p => ({ projectId: p.projectId, spaceId: `project:${p.projectId}`, knowledgePath: p.knowledgePath, weight: p.projectId === registration.projectId ? 1 : 0.88, reason: p.projectId === registration.projectId ? 'primary' : input.scope }));
+      scopes.push(...this.sharedScopes(registration, input.scope));
+    }
+    const result = await super.search({ ...input, project, scopes });
+    result.results = result.results.map(row => {
+      const run = this.store.listRuns(row.scope_project_id).find(r => r.promotedAt && r.staging?.operations?.some(op => op.path === row.entry_id));
+      const source = this.store.getProject(row.scope_project_id) || this.store.state.sharedScopes.find(s => s.id === row.scope_project_id);
+      return { ...row, projectName: source?.name || row.scope_project_id, path: row.entry_id, snippet: row.chunk_text, score: row.relevance_score, projectId: row.scope_project_id, commitSha: run?.commitSha || null };
+    });
+    return result;
+  }
+  async ask(input) {
+    const result = await this.search(input);
+    const citations = result.results.slice(0, 5).map((r, i) => ({ index: i + 1, ref: i + 1, projectId: r.scope_project_id, projectName: r.projectName, spaceId: r.space_id, commitSha: r.commitSha, score: r.relevance_score, entryId: r.entry_id, path: r.entry_id, title: r.title, text: r.chunk_text }));
+    return { ...result, answer: citations.length ? citations.map(r => `${r.index}. ${r.title}: ${r.text}`).join('\n') : '知识库中没有找到相关内容。', citations };
+  }
+  async get(input) {
+    const registration = this.resolve(input);
+    const scope = input.spaceId && this.store.state.sharedScopes.find(s => `${s.kind}:${s.id}` === input.spaceId && s.brainId === registration.brainId);
+    if (input.spaceId && !scope && input.spaceId !== `project:${registration.projectId}`) throw new DomainError('PROJECT_NOT_FOUND', '知识范围与项目归属不匹配。', { status: 404 });
+    const project = scope ? { projectId: scope.id, knowledgePath: scope.knowledgePath } : registration;
+    const entryId = String(input.entryId || input.entry || '').replace(/\\/g, '/');
+    const target = path.resolve(project.knowledgePath, entryId);
+    if (!entryId || !/\.md$/i.test(target) || !this.layout.isPathInside(project.knowledgePath, target, { realpath: true })) throw new DomainError('PATH_OUTSIDE_ROOT', '知识文件越界。', { status: 403 });
+    if (!fs.existsSync(target) || !fs.statSync(target).isFile() || fs.lstatSync(target).isSymbolicLink()) throw new DomainError('PROJECT_NOT_FOUND', '知识文件不存在。', { status: 404 });
+    if (scope && entryId.startsWith('memories/') && (entryId !== 'memories/confirmed.md' || !this.memories?.validFile(scope))) throw new DomainError('PROJECT_NOT_FOUND', '记忆尚未完成确认写入。', { status: 404 });
+    return { ok: true, projectId: project.projectId, projectSlug: project.projectId, entryId, source: 'markdown', chunks: [{ chunk_text: fs.readFileSync(target, 'utf8'), entry_id: entryId, space_id: scope ? `${scope.kind}:${scope.id}` : `project:${project.projectId}` }] };
+  }
+  async history(input) {
+    const project = this.resolve(input);
+    const results = listMarkdownFiles(project.knowledgePath).filter(file => this.layout.isPathInside(path.join(project.knowledgePath, 'changes'), file, { realpath: true })).map(file => {
+      const content = fs.readFileSync(file, 'utf8');
+      return { entry_id: path.relative(project.knowledgePath, file).replace(/\\/g, '/'), title: (/^#\s+(.+)$/m.exec(content) || [null, path.basename(file)])[1], chunk_text: content.slice(0, 900), updated_at: fs.statSync(file).mtime.toISOString() };
+    }).sort((a, b) => b.updated_at.localeCompare(a.updated_at)).slice(0, Math.min(100, Math.max(1, Number(input.limit) || 20)));
+    return { ok: true, projectId: project.projectId, projectSlug: project.projectId, backend: 'markdown', source: 'markdown', results };
+  }
+}
+
+module.exports = { EngineRetrieval };

package/_modules/knowledge-engine/src/runtime/README.md

@@ -0,0 +1,7 @@
+# 迁入的知识运行逻辑
+
+来源：project-knowledge-base/_site/lib，基线 0c62f528f66794ca5de055a137f632dfc5c57bc3。
+
+复用提交证据冻结、会话边界绑定、检索事实校验、提示词、安全工具策略、晋升事务及崩溃恢复。只迁入知识运行职责，没有复制外壳的项目注册表、SettingsStore、凭据或旧 LanceDB/embedding 写入能力。
+
+构造函数改为注入 layout 与只读项目投影/运行状态适配器；内容哈希提取为零依赖文件。项目和配置的所有权仍在外壳，引擎本地登记只是运行所需投影。向量召回接 vector-hub，不启动第二份索引。