@sanqianx/project-knowledge 5.0.18 → 5.0.20-rc.1

package/_modules/knowledge-engine/README.md

@@ -114,6 +114,10 @@ node src/bin.js serve [--port 5790] [--host 127.0.0.1] [--data DIR]
 
 ## 验证与尚未验收项
 
+默认维护模型额度或余额不足时，不会成功生成知识；提交任务仍先持久化。SDK 明确报告 billing 错误时记录 `MODEL_QUOTA_EXHAUSTED`，请求限流单独记录 `MODEL_RATE_LIMITED`，不把任意 HTTP 429 当作余额耗尽。同项目后续提交保持排队，失败与排队记录跨重启保留；恢复额度或更换默认维护模型后需显式重试前一条失败提交，不会自动消耗额度反复重试。
+
+`/api/snapshot` 的兼容扩展字段 `maintenance` 包含执行启用状态、事件消费启用状态及按当前项目过滤的 journal 故障。建单前的消费故障不会伪造提交运行；外壳展示“提交事件消费受阻”，不能将零条运行当作没有提交。故障变化和恢复通过现有 progress 流通知，稳定故障不产生重复刷新事件。未启动服务时，Hook 已捕获的事件保留于 journal，服务消费后才生成分析任务。
+
 `npm test` 覆盖真实 Git/Hook、真实分项目 journal、真实 vector-hub 文件索引、晋升、重复抑制、FIFO/并发、记忆、旧格式拒绝、新版恢复及进程隔离。自动测试中的模型和 embedding 是可控替身。
 
 `npm run test:web` 使用兄弟源码仓库启动隔离的五服务网页环境，只有模型与 embedding 是替身。单一 1920×1080 视口验证双目录 UI 导入、真实 Hook 到自动刷新、原生消息流与中止、快速项目切换/草稿/历史、迟到检索及文件响应、领域检索、记忆落盘、四 iframe 身份与主题、唯一进度连接、诊断关闭和保留数据解绑；不会在用户代码仓库提交。该脚本是开发验收工具，不属于引擎生产运行依赖。

package/_modules/knowledge-engine/src/analysis-contract.js

@@ -14,10 +14,11 @@ function frameFrozenEvidence(prompt) {
 }
 
 function memoryCandidateContract(entryId) {
-  return `\nMEMORY CANDIDATE CONTRACT: When the frozen owner explicitly states a durable preference, quote it exactly in a written knowledge document and propose memoryCandidates in manifest.json. With no explicit owner preference, omit candidates; never infer preferences from code style, test fixtures or assistant claims alone.
-Shape: [{"text":"the summarized preference","entryId":${JSON.stringify(entryId)},"quote":"an exact excerpt from that written document","scopeType":"project"}].
+  return `\nMEMORY CANDIDATE CONTRACT: An automatic long-term memory may ONLY be the owner's own explicit, durable, cross-project statement: a global convention or a domain norm the owner stated in a frozen user event whose inputOrigin is "human". Assistant replies, generated knowledge documents, code, test fixtures and agent-delegation prompts are never owner statements, even when they contain preference-like wording. Project architecture, version facts, one-off fixes and temporary task discipline belong in project knowledge only: do not propose them as candidates. With no such owner statement, omit candidates entirely.
+Shape: [{"text":"the owner's verbatim durable statement or a contiguous excerpt of quote; never a paraphrase","entryId":${JSON.stringify(entryId)},"quote":"the owner's exact original sentence, copied verbatim into that written document","sourceEventId":"the eventId of that frozen human user event","sourceHash":"that event's contentHash","scopeType":"domain" or "global","eligibility":{"durable":true,"crossProject":true,"reason":"why this statement is long-term rather than one-off, grounded in the owner's wording","scopeReason":"why it applies across the whole domain or all projects"}}].
+The engine independently verifies every field against the frozen conversation snapshot of this claim: sourceEventId must be one of its user events with inputOrigin "human"; sourceHash must equal that event's contentHash; quote must appear verbatim both in that event's content and in the entryId document; eligibility must be fully attested with non-empty reasons; scopeType must be "domain" or "global" — automatic candidates have no project scope. A failed check only rejects the candidate, never the knowledge promotion, so attest honestly: self-reported labels cannot substitute for the frozen source, and one-time instructions, project-local conventions or delegated task orders must not be proposed.
 entryId MUST equal an operations[].path for a create/replace in THIS manifest. It is the final knowledge-relative .md document path, NOT a candidate identifier, NOT an absolute path, NOT files/<path>. For example, when the quoted text is in files/${entryId}, entryId is ${JSON.stringify(entryId)}. If another written document contains the quote, use that document's exact operations[].path instead.
-quote must appear verbatim in that document and have at least 8 characters; text is 1–2000 characters. Check the document and entryId before submitting the manifest. scopeType is project (default), domain or global. Recommend domain/global only when the quoted owner requirement explicitly applies across that domain/all projects; ambiguous or local requirements stay project-scoped. Do not invent scope target IDs. Candidates remain unconfirmed until the user reviews content and scope.`;
+quote must appear verbatim in that document and have at least 8 characters; text is 1–2000 characters. Check the document, the entryId and the frozen event before submitting the manifest. Prefer "domain" when the owner's wording explicitly spans the current domain and "global" when it spans all projects; do not invent scope target IDs. Candidates remain unconfirmed until the user reviews content and scope.`;
 }
 
 function requireAnalysisOutput(manifestPath) {

package/_modules/knowledge-engine/src/analysis-failures.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const failures = {
+  MODEL_QUOTA_EXHAUSTED: '默认维护模型的额度或余额不足。提交证据与失败记录已保留；恢复额度或更换默认模型后，请重试此提交。',
+  MODEL_RATE_LIMITED: '默认维护模型请求受限。提交证据与失败记录已保留，请稍后重试。',
+  MODEL_AUTH_FAILED: '默认维护模型认证失败。提交证据与失败记录已保留，请检查凭据后重试。',
+  AI_RUNTIME_REQUIRED: '后台分析运行时不可用，请修复安装后重试。',
+  ANALYSIS_OUTPUT_MISSING: '后台分析未生成有效文件，提交证据与失败记录已保留，请重试。',
+  MODEL_FAILED: '后台 Agent 分析失败。提交证据与失败记录已保留，请检查默认维护模型后重试。',
+};
+
+// Provider text can echo credentials. Classify structured codes only; neither
+// raw messages nor unknown codes may cross the worker IPC boundary.
+function classifyAnalysisFailure(input) {
+  const codes = new Set(), statuses = new Set(), seen = new Set();
+  function collect(value, depth = 0) {
+    if (typeof value === 'string') { codes.add(value.toLowerCase()); return; }
+    if (!value || typeof value !== 'object' || depth > 3 || seen.has(value)) return;
+    seen.add(value);
+    for (const key of ['code', 'type']) if (typeof value[key] === 'string') codes.add(value[key].toLowerCase());
+    if (value.status !== undefined) statuses.add(Number(value.status));
+    collect(value.error, depth + 1); collect(value.cause, depth + 1);
+  }
+  collect(input);
+  const has = (...values) => values.some(value => codes.has(value));
+  if (has('billing_error', 'insufficient_quota', 'quota_exceeded', 'insufficient_balance', 'model_quota_exhausted')) return 'MODEL_QUOTA_EXHAUSTED';
+  if (has('authentication_failed', 'authentication_error', 'model_auth_failed') || statuses.has(401)) return 'MODEL_AUTH_FAILED';
+  if (has('rate_limit', 'rate_limit_error', 'model_rate_limited') || statuses.has(429)) return 'MODEL_RATE_LIMITED';
+  if (has('module_not_found', 'ai_runtime_required')) return 'AI_RUNTIME_REQUIRED';
+  if (has('analysis_output_missing')) return 'ANALYSIS_OUTPUT_MISSING';
+  return 'MODEL_FAILED';
+}
+
+function analysisFailure(code) {
+  code = Object.hasOwn(failures, code) ? code : 'MODEL_FAILED';
+  return Object.assign(new Error(failures[code]), { code, retryable: true });
+}
+
+module.exports = { classifyAnalysisFailure, analysisFailure };

package/_modules/knowledge-engine/src/analysis-worker.js

@@ -4,6 +4,7 @@ const { pathToFileURL } = require('node:url');
 const { evaluateAutomationToolUse } = require('./runtime/automation-config');
 const { RuntimeLayout } = require('./runtime/layout');
 const { ANALYSIS_SYSTEM_INSTRUCTIONS, requireAnalysisOutput } = require('./analysis-contract');
+const { classifyAnalysisFailure, analysisFailure } = require('./analysis-failures');
 
 const abortController = new AbortController();
 process.once('SIGTERM', () => abortController.abort());
@@ -11,6 +12,7 @@ process.once('disconnect', () => abortController.abort());
 process.on('message', message => { if (message?.type === 'cancel') abortController.abort(); });
 
 process.once('message', async job => {
+  let failureCode = 'MODEL_FAILED';
   try {
     const { query } = await import(pathToFileURL(require.resolve('@anthropic-ai/claude-agent-sdk')).href);
     const layout = new RuntimeLayout(job.stagingPath);
@@ -40,15 +42,17 @@ process.once('message', async job => {
       }] }] },
     } });
     for await (const message of turn) {
+      if (message.type === 'assistant' && message.error) failureCode = classifyAnalysisFailure(message.error);
       if (message.type === 'result') completed = message.subtype === 'success' && !message.is_error;
     }
-    if (!completed) throw new Error('MODEL_FAILED');
+    if (!completed) throw analysisFailure(failureCode);
     requireAnalysisOutput(job.manifestPath);
     process.send({ type: 'complete' }, () => process.exit(0));
   } catch (error) {
     // SDK/provider messages can echo credentials. Only controlled codes leave
     // this isolated process; raw output is never written to state or logs.
-    const code = error.code === 'MODULE_NOT_FOUND' ? 'AI_RUNTIME_REQUIRED' : error.code === 'ANALYSIS_OUTPUT_MISSING' ? error.code : 'MODEL_FAILED';
+    const classified = classifyAnalysisFailure(error);
+    const code = classified === 'MODEL_FAILED' ? failureCode : classified;
     process.send({ type: 'failure', code }, () => process.exit(1));
   }
 });

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

@@ -41,6 +41,7 @@ class EngineCoordinator extends EventEmitter {
     this.sharedIndexDirty = new Set();
     this.sharedIndexQueue = Promise.resolve();
     this.memories = new MemoryService(store, {
+      readSnapshot: (projectId, commitSha) => this.conversations.readSnapshot(projectId, commitSha),
       getIndexStatus: scope => scope && this.memoryIndexUpdates.has(scope.id) && this.sharedIndexJobs.has(scope.id) ? 'pending' : null,
       onMaterialized: scope => { this.memoryIndexUpdates.add(scope.id); this.indexSharedScope(scope).catch(() => {}); },
       onSyncChange: (scope, code) => {
@@ -136,6 +137,7 @@ class EngineCoordinator extends EventEmitter {
     return job;
   }
   async drainJournals() {
+    const prior = JSON.stringify([...this.journalFailures.values()]);
     this.draining = true;
     try {
       await this.bridge.registerConsumer('knowledge-engine', { journals: ['*'] });
@@ -156,8 +158,14 @@ class EngineCoordinator extends EventEmitter {
     finally {
       this.journalError = this.journalFailures.size ? '事件消费异常，未消费证据与游标已保留，请查看诊断日志。' : null;
       this.draining = false;
+      if (JSON.stringify([...this.journalFailures.values()]) !== prior) this.emit('progress', this.store.addEvent({ type: 'knowledge.journal', summary: this.journalError ? '提交事件消费受阻，请查看维护状态' : '提交事件消费已恢复' }));
     }
   }
+  maintenanceStatus(projectId) {
+    const project = projectId ? this.store.getProject(projectId) : null;
+    const failures = [...this.journalFailures.values()].filter(failure => !projectId || failure.journalId === 'connection' || (failure.journalId === 'global' && !failure.projectId) || failure.projectId === projectId || failure.journalId === project?.journalId);
+    return { projectId: projectId || null, executionEnabled: this.executionEnabled && (!projectId || !!project && (!this.allowedProjects || this.allowedProjects.has(projectId))), consuming: this.consume, journal: { error: failures.length ? this.journalError : null, failures } };
+  }
   async recordJournalFailure(journalId, error) {
     const context = error.journalContext || {};
     const failure = { journalId, sequence: context.sequence ?? null, projectId: context.projectId || null, code: error.code || 'JOURNAL_FAILED', message: this.safeMessage(error.message) };

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

@@ -4,6 +4,7 @@ const path = require('node:path');
 const { frameFrozenEvidence, memoryCandidateContract } = require('./analysis-contract');
 const { finalizeAnalysisOutput } = require('./analysis-output');
 const { freezeKnowledgeTargets } = require('./knowledge-targets');
+const { analysisFailure } = require('./analysis-failures');
 
 class HeadlessAnalyzer {
   get sourceReadMode() { return 'isolated-frozen-evidence'; }
@@ -42,7 +43,7 @@ class HeadlessAnalyzer {
       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 }));
+        else if (message?.type === 'failure') stop(analysisFailure(message.code));
       });
       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

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

@@ -5,6 +5,7 @@ const crypto = require('node:crypto');
 const AtomicFile = require('./runtime/atomic-file');
 const { RuntimeLayout } = require('./runtime/layout');
 const { validateProjectId, DomainError } = require('./runtime/contracts');
+const { MemoryEligibility } = require('./memory-eligibility');
 
 const TYPES = ['global', 'domain', 'project'];
 const normalized = text => String(text).toLowerCase().replace(/\s+/g, ' ').trim();
@@ -15,6 +16,7 @@ class MemoryService {
     this.store = store; this.layout = new RuntimeLayout(store.dataDir); this.onMaterialized = options.onMaterialized;
     this.syncErrors = new Map(); this.closed = false; this.onSyncChange = options.onSyncChange; this.writes = new Set();
     this.getIndexStatus = options.getIndexStatus;
+    this.eligibility = new MemoryEligibility({ readSnapshot: options.readSnapshot || null });
   }
   lock() { return this.layout.getRuntimePath('locks', 'memories.lock'); }
   scopeOf(memory) { return { type: memory.scopeType || 'global', id: memory.scopeId || memory.brainId || 'brain-default' }; }
@@ -101,6 +103,7 @@ class MemoryService {
     const project = this.store.getProject(run.projectId);
     if (!project || !run.promotedAt) return report;
     const candidates = Array.isArray(run.staging?.memoryCandidates) ? run.staging.memoryCandidates : [];
+    const snapshot = this.eligibility.resolve(run);
     const before = this.store.state.memories, next = [...before];
     for (const [index, raw] of candidates.slice(0, 20).entries()) {
       const reject = code => report.rejected.push({ index, code });
@@ -114,12 +117,14 @@ class MemoryService {
       if (!this.layout.isPathInside(project.knowledgePath, file, { realpath: true })) { reject('PATH_OUTSIDE_ROOT'); continue; }
       try { if (!fs.readFileSync(file, 'utf8').includes(quote)) { reject('QUOTE_MISMATCH'); continue; } }
       catch { reject('EVIDENCE_UNREADABLE'); continue; }
+      const provenance = this.eligibility.verify(raw, snapshot, project);
+      if (!provenance.ok) { reject(provenance.code); continue; }
       const brainId = project.brainId || 'brain-default';
-      const scopeType = raw.scopeType === 'global' ? 'global' : raw.scopeType === 'domain' && project.domainId ? 'domain' : 'project';
-      const scopeId = scopeType === 'global' ? brainId : scopeType === 'domain' ? project.domainId : project.projectId;
+      const scopeType = raw.scopeType;
+      const scopeId = scopeType === 'global' ? brainId : project.domainId;
       const key = fingerprint(brainId, scopeType, scopeId, text);
-      if (next.some(m => m.captureFingerprint === key || fingerprint(m.brainId || 'brain-default', this.scopeOf(m).type, this.scopeOf(m).id, m.text) === key || !m.scopeType && m.evidence.projectId === project.projectId && normalized(m.originalText || m.text) === normalized(text))) { report.deduplicated++; continue; }
-      next.push({ id: `memory-${crypto.randomUUID()}`, fingerprint: key, captureFingerprint: key, brainId, domainId: project.domainId || null, scopeType, scopeId, text, originalText: text, status: 'candidate', evidence: { projectId: project.projectId, commitSha: run.commitSha, runId: run.runId, entryId, quote }, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() });
+      if (next.some(m => m.captureFingerprint === key || fingerprint(m.brainId || 'brain-default', this.scopeOf(m).type, this.scopeOf(m).id, m.text) === key || !m.scopeType && m.evidence?.projectId === project.projectId && normalized(m.originalText || m.text) === normalized(text))) { report.deduplicated++; continue; }
+      next.push({ id: `memory-${crypto.randomUUID()}`, fingerprint: key, captureFingerprint: key, brainId, domainId: project.domainId || null, scopeType, scopeId, text, originalText: text, status: 'candidate', sourceEventId: provenance.sourceEventId, sourceHash: provenance.sourceHash, eligibility: provenance.eligibility, evidence: { projectId: project.projectId, commitSha: run.commitSha, runId: run.runId, entryId, quote }, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString() });
       report.accepted++;
     }
     if (report.accepted) {
@@ -183,7 +188,7 @@ class MemoryService {
       // Preserve legacy global bytes until the user actually edits that record.
       const scopeText = m.scopeType ? `适用范围：${{ global: '全局', domain: '领域', project: '项目' }[scope.type]} · ${scope.id}\n\n` : '';
       const text = m.scopeType ? m.text.replace(/^\s*(#{1,6})\s/gm, '\\$1 ') : m.text;
-      const source = m.sourceType === 'manual' ? '手动添加（用户确认）' : `${m.evidence.projectId} · ${m.evidence.commitSha} · ${m.evidence.entryId}`;
+      const source = m.sourceType === 'manual' ? '手动添加（用户确认）' : m.evidence ? `${m.evidence.projectId} · ${m.evidence.commitSha} · ${m.evidence.entryId}` : '历史记录（来源未记录）';
       return `## ${m.id}\n\n${scopeText}${text}\n\n来源：${source}\n`;
     }).join('\n');
   }

package/_modules/knowledge-engine/src/memory-eligibility.js

@@ -0,0 +1,74 @@
+'use strict';
+
+// Hard provenance gate for automatic long-term memory admission. The
+// maintenance model owns the semantic judgment (its prompt contract demands
+// durable, cross-project owner preferences); this gate never re-classifies
+// text and never trusts model self-reports over the frozen snapshot of the
+// claim being captured.
+const SHARED_SCOPES = new Set(['domain', 'global']);
+
+function indexUserEvents(snapshot) {
+  const events = new Map();
+  for (const turn of snapshot?.turns || []) {
+    for (const event of turn.userEvents || []) {
+      if (event?.eventId) events.set(String(event.eventId), event);
+    }
+  }
+  return events;
+}
+
+function conversationReferences(run) {
+  const references = new Set();
+  for (const operation of run?.staging?.operations || []) {
+    for (const reference of operation.evidenceReferences || []) {
+      if (typeof reference === 'string' && reference.startsWith('conversation:')) references.add(reference.slice('conversation:'.length));
+    }
+  }
+  return references;
+}
+
+class MemoryEligibility {
+  constructor(options = {}) {
+    this.readSnapshot = typeof options.readSnapshot === 'function' ? options.readSnapshot : null;
+  }
+
+  // The snapshot must exist AND be bound to this run's promoted operations
+  // through a `conversation:<snapshotHash>` evidence reference, so a foreign
+  // or later-frozen conversation can never vouch for this claim.
+  resolve(run) {
+    if (!this.readSnapshot) return null;
+    const references = conversationReferences(run);
+    if (!references.size) return null;
+    let snapshot = null;
+    try { snapshot = this.readSnapshot(run.projectId, run.commitSha); } catch { return null; }
+    return snapshot && references.has(snapshot.snapshotHash) ? snapshot : null;
+  }
+
+  verify(candidate, snapshot, project) {
+    if (!snapshot) return { ok: false, code: 'SNAPSHOT_UNAVAILABLE' };
+    const sourceEventId = String(candidate.sourceEventId || '');
+    if (!sourceEventId) return { ok: false, code: 'SOURCE_EVENT_MISSING' };
+    const event = indexUserEvents(snapshot).get(sourceEventId);
+    if (!event) return { ok: false, code: 'SOURCE_EVENT_NOT_FOUND' };
+    if ((event.inputOrigin || 'unknown') !== 'human') return { ok: false, code: 'SOURCE_NOT_HUMAN' };
+    if (String(candidate.sourceHash || '') !== String(event.contentHash || '')) return { ok: false, code: 'SOURCE_HASH_MISMATCH' };
+    if (!String(event.content || '').includes(String(candidate.quote || '').trim())) return { ok: false, code: 'QUOTE_NOT_IN_SOURCE' };
+    if (!String(candidate.quote || '').includes(String(candidate.text || '').trim())) return { ok: false, code: 'TEXT_NOT_IN_QUOTE' };
+    const eligibility = candidate.eligibility;
+    if (!eligibility || typeof eligibility !== 'object' || Array.isArray(eligibility)) return { ok: false, code: 'ELIGIBILITY_MISSING' };
+    if (eligibility.durable !== true) return { ok: false, code: 'ELIGIBILITY_NOT_DURABLE' };
+    if (eligibility.crossProject !== true) return { ok: false, code: 'ELIGIBILITY_NOT_CROSS_PROJECT' };
+    if (!String(eligibility.reason || '').trim()) return { ok: false, code: 'ELIGIBILITY_REASON_MISSING' };
+    if (!String(eligibility.scopeReason || '').trim()) return { ok: false, code: 'ELIGIBILITY_SCOPE_REASON_MISSING' };
+    if (!SHARED_SCOPES.has(candidate.scopeType)) return { ok: false, code: 'SCOPE_NOT_SHARED' };
+    if (candidate.scopeType === 'domain' && !project.domainId) return { ok: false, code: 'SCOPE_DOMAIN_UNBOUND' };
+    return {
+      ok: true,
+      sourceEventId,
+      sourceHash: String(event.contentHash),
+      eligibility: { durable: true, crossProject: true, reason: String(eligibility.reason).trim(), scopeReason: String(eligibility.scopeReason).trim() },
+    };
+  }
+}
+
+module.exports = { MemoryEligibility };

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

@@ -47,7 +47,8 @@ function intent(query) {
   const text = String(query || '').trim();
   if (/^(?:hello|hi|hey|你好|您好|早上好|晚上好|在吗)[\s!！。?？]*$/i.test(text)) return 'greeting';
   if (/^(?:为什么|怎么回事|这是什么意思|继续|然后呢|展开说说|why|continue|tell me more)[\s!！。?？]*$/i.test(text)) return 'followup';
-  if (/(你|本轮|本次|刚才|上一条|这段).*(知识|记忆|上下文|context|memory).*(来源|哪里|什么地方|收到|读取|获取|from|received)/i.test(text)) return 'followup';
+  const concreteTask = /(修复|实现|新增|设计|为什么|为何|如何|怎样|避免|并发|草稿|implement|fix|design|why|how)/i.test(text);
+  if (!concreteTask && /(你|本轮|本次|刚才|上一条|这段).*(知识|记忆|上下文|context|memory).*(来源|哪里|什么地方|收到|读取|获取|from|received)/i.test(text)) return 'followup';
   if (/(最近|最新|上次|上一[次回]|recent|latest|last)/i.test(text) && /(进度|开发|提交|修改|更新|改动|progress|commit|develop|change|update)/i.test(text)) return 'recent';
   return 'search';
 }
@@ -80,6 +81,23 @@ function lexical(candidates, query, ignoredTerms = []) {
 }
 
 function rank(candidates, query, scoreIdentity, options = {}) {
+  // Named technologies select evidence, not merely a similar subject. A
+  // calibrated embedding can place an unrelated document nearby; it cannot
+  // establish that PostgreSQL/OpenTelemetry exists in the current knowledge.
+  // Filenames are excluded because new files legitimately seek analogies.
+  const topicQuery = String(query).replace(/[A-Za-z0-9_./\\-]+\.[A-Za-z0-9]{1,8}\b/g, '');
+  const named = [...new Set((topicQuery.match(/\b[A-Z][A-Za-z0-9]*[a-z][A-Z][A-Za-z0-9]*\b/g) || []).map(name => name.toLowerCase()))];
+  if (named.length) {
+    const documented = new Map();
+    for (const c of candidates) {
+      const key = `${c.spaceId}:${c.entryId}`;
+      const text = `${c.title}\n${c.chunkText}`.toLowerCase();
+      const found = documented.get(key) || new Set();
+      for (const name of named) if (text.includes(name)) found.add(name);
+      documented.set(key, found);
+    }
+    candidates = candidates.filter(c => named.every(name => documented.get(`${c.spaceId}:${c.entryId}`)?.has(name)));
+  }
   // A resolved commit already constrains provenance. Repeated SHA text in a
   // heading is not evidence for the topic asked about within that commit.
   lexical(candidates, query, options.commitPrefixes || []);

package/_modules/knowledge-engine/src/runtime/commit-conversation-binder.js

@@ -9,6 +9,7 @@ function projectEvent(event) {
     sequence: event.sequence,
     content: event.content,
     contentHash: event.contentHash,
+    inputOrigin: event.inputOrigin || 'unknown',
     capturedAt: event.capturedAt,
   };
 }

package/_modules/knowledge-engine/src/runtime/commit-prompt.js

@@ -33,18 +33,21 @@ function formatRequirements(records) {
   ].join('\n')).join('\n');
 }
 
-function formatConversationUserTruth(snapshot) {
-  if (!snapshot || !Array.isArray(snapshot.turns) || snapshot.turns.length === 0) return REQUIREMENT_UNAVAILABLE;
-  return snapshot.turns.flatMap(turn => turn.userEvents.map(event => [
-    `- turnId: ${turn.turnId}`,
-    `  eventId: ${event.eventId}`,
-    `  source/session: ${turn.source}/${turn.sessionId || '(unavailable)'}`,
+function formatConversationUserTruth(snapshot) {
+  if (!snapshot || !Array.isArray(snapshot.turns) || snapshot.turns.length === 0) return REQUIREMENT_UNAVAILABLE;
+  const rendered = snapshot.turns.flatMap(turn => turn.userEvents.map(event => [
+    `- turnId: ${turn.turnId}`,
+    `  eventId: ${event.eventId}`,
+    `  inputOrigin: ${event.inputOrigin || 'unknown'}`,
+    `  contentHash: ${event.contentHash}`,
+    `  source/session: ${turn.source}/${turn.sessionId || '(unavailable)'}`,
     `  binding: ${turn.bindingKind}`,
     `  capturedAt: ${event.capturedAt}`,
     '  userPrompt: |',
-    ...String(event.content || '').split(/\r?\n/).map(line => `    ${line}`),
-  ].join('\n'))).join('\n');
-}
+    ...String(event.content || '').split(/\r?\n/).map(line => `    ${line}`),
+  ].join('\n'))).join('\n');
+  return `inputOrigin marks who typed each frozen user event: only "human" is the owner speaking; "agent-delegation" is a delegated task order from another agent; "unknown" cannot be verified. Memory candidates may rely on "human" events only.\n${rendered}`;
+}
 
 function formatAssistantEvidence(snapshot) {
   if (!snapshot || !Array.isArray(snapshot.turns)) return '(no assistant conversation evidence was frozen)';

package/_modules/knowledge-engine/src/runtime/conversation-store.js

@@ -46,6 +46,7 @@ function normalizeConversationEvent(projectId, input = {}) {
     source: String(input.source || ''),
     eventType: String(input.eventType || ''),
     role,
+    inputOrigin: ['human', 'agent-delegation'].includes(input.inputOrigin) ? input.inputOrigin : 'unknown',
     content,
     contentHash: sha256(content),
     sessionId: optionalString(input.sessionId),
@@ -235,6 +236,7 @@ class ConversationStore {
       source: bridgeEvent.source,
       eventType: bridgeEvent.eventType,
       role: bridgeEvent.role,
+      inputOrigin: bridgeEvent.inputOrigin || bridgeEvent.meta?.inputOrigin || /:origin=(human|agent-delegation|unknown)$/.exec(String(bridgeEvent.eventKey || ''))?.[1],
       content: bridgeEvent.content == null ? '' : bridgeEvent.content,
       sessionId: bridgeEvent.sessionId,
       turnId: bridgeEvent.turnId,

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

@@ -143,7 +143,7 @@ async function api(method, pathname, search, body, store, coordinator, ctx) {
   if (method === 'GET' && pathname === '/api/events') return { events: store.listEvents(search.get('limit')).filter(e => !search.get('projectId') || e.projectId === search.get('projectId')) };
   if (method === 'POST' && pathname === '/api/events' && ctx.debug) return { event: store.addEvent(body) };
   if (method === 'POST' && pathname === '/api/bridge/notify') { if (coordinator.consume) coordinator.drain(); return { accepted: true }; }
-  if (method === 'GET' && pathname === '/api/snapshot') return { projects: store.listProjects(), ...(search.get('summary') === '1' ? store.listRunPage({ projectId: search.get('projectId'), limit: search.get('limit') || 50, before: search.get('before') }) : { runs: store.listRuns(search.get('projectId')) }), events: store.listEvents(50), memories: coordinator.memories.list(), sharedScopes: store.state.sharedScopes };
+  if (method === 'GET' && pathname === '/api/snapshot') return { projects: store.listProjects(), ...(search.get('summary') === '1' ? store.listRunPage({ projectId: search.get('projectId'), limit: search.get('limit') || 50, before: search.get('before') }) : { runs: store.listRuns(search.get('projectId')) }), events: store.listEvents(50), memories: coordinator.memories.list(), sharedScopes: store.state.sharedScopes, maintenance: coordinator.maintenanceStatus(search.get('projectId')) };
   throw httpError(404, 'NOT_FOUND', '接口不存在。');
 }
 

package/_site/_test/agent-capture-mcp-ui-test.js

@@ -1,67 +1,67 @@
-'use strict';
-const assert = require('node:assert/strict');
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const http = require('node:http');
-const { createRequire } = require('node:module');
-const coreRoot = path.resolve(process.env.KB_CAPTURE_TEST_CORE_ROOT || path.join(__dirname, '../..'));
-const fromCore = createRequire(path.join(coreRoot, 'package.json'));
-const { createRuntime, initializeRuntime, createRequestHandler } = fromCore('./_site/lib/server-app');
-const { BridgeAdapter } = fromCore('./_site/lib/bridge-adapter');
-const { ModuleBridge } = fromCore('./_site/lib/module-bridge');
-const { findChrome } = require('./helpers/find-chrome');
-const { launchCdpBrowser, waitFor } = require('./helpers/cdp-browser');
-
-const HOSTILE_DETAIL = '<img src=x onerror="window.__kbXssProbe=1"> INJECT-STATUS-MARKER sk-abcdef123456';
-
-function clientFixture(client, label) {
-  const mcpCapable = client === 'claude' || client === 'codex';
-  return {
-    client, label, available: false, configFound: false,
-    knowledgeIntegration: { ok: true, state: 'installed' },
-    automaticContext: { supported: client !== 'opencode', configured: false, state: 'check-failed', detail: HOSTILE_DETAIL },
-    developmentCapture: { ok: true, state: 'installed', installed: true, detail: HOSTILE_DETAIL },
-    mcpStartup: mcpCapable ? { state: 'failed', checkedAt: new Date().toISOString(), scope: 'client:' + client, code: 'PROBE_TIMEOUT', expectedVersion: '9.9.9-test', detail: HOSTILE_DETAIL } : undefined,
-  };
-}
-
-async function main() {
-  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-agent-mcp-ui-'));
-  const dataDir = path.join(temp, 'data');
-  const homeDir = path.join(temp, 'home');
-  const eventsHome = path.join(dataDir, 'events');
-  const offline = http.createServer((req, res) => { res.writeHead(503, { 'content-type': 'application/json' }); res.end(JSON.stringify({ ok: false, error: { message: 'offline stub' } })); });
-  await new Promise(resolve => offline.listen(0, '127.0.0.1', resolve));
-  const offlineUrl = 'http://127.0.0.1:' + offline.address().port;
-  const runtime = createRuntime({ dataDir, analysisOwner: 'engine', bridgeAdapter: new BridgeAdapter({ dataDir, bridgeHomeDir: eventsHome }), moduleBridge: new ModuleBridge({ terminalUrl: offlineUrl, engineUrl: offlineUrl, eventBridgeUrl: offlineUrl, vectorHubUrl: offlineUrl }) });
-  await initializeRuntime(runtime);
-  const server = http.createServer(createRequestHandler(runtime, { integrationOptions: { homeDir, env: {}, commandResolver: () => '' } }));
-  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
-  const base = 'http://127.0.0.1:' + server.address().port;
-  const payload = JSON.stringify({ bridge: { ok: true }, scan: { state: 'ready' }, clients: [clientFixture('claude', 'Claude Code'), clientFixture('codex', 'Codex'), clientFixture('zcode', 'ZCode'), clientFixture('opencode', 'OpenCode')] });
-  let browser;
-  try {
-    browser = await launchCdpBrowser({ chrome: findChrome(), profileDir: path.join(temp, 'browser'), url: base, width: 1440, height: 900 });
-    const run = expression => browser.evaluate(expression);
-    const click = selector => run('document.querySelector(' + JSON.stringify(selector) + ').click()');
-    await run('(() => { const original = window.fetch; window.__originalFetch = original; window.fetch = (input, init) => { const url = String(input && input.url || input); if (url.includes(\'/api/integrations/status\')) { return Promise.resolve({ ok: true, json: async () => (' + payload + ') }); } return original(input, init); }; })()');
-    await click('#openSystem');
-    await waitFor(() => run("document.querySelectorAll('#agentCaptureList .agent-capture-row').length === 4"), 'capture rows render');
-    assert(await run("document.getElementById('agentCaptureList').textContent.includes('PROBE_TIMEOUT')"), 'the MCP startup failure code must be rendered for MCP-capable clients');
-    const claudeRowHtml = await run("document.querySelector('#agentCaptureList .agent-capture-row').innerHTML");
-    assert(claudeRowHtml.includes('&lt;img'), 'hostile mcpStartup detail must be HTML-escaped, got: ' + claudeRowHtml.slice(0, 300));
-    assert(!claudeRowHtml.includes('<img'), 'no raw hostile markup may reach the DOM');
-    assert.equal(await run('window.__kbXssProbe'), undefined, 'the hostile onerror must never execute');
-    const smalls = await run("[...document.querySelectorAll('#agentCaptureList small')].map(el => el.textContent).join('|')");
-    assert(smalls.split('|').some(text => text.startsWith('MCP')), 'the MCP diagnostic is its own line item, got: ' + smalls);
-    assert.equal(browser.exceptions.length, 0, JSON.stringify(browser.exceptions));
-    console.log('agent-capture-mcp-ui-test PASS (MCP line rendered separately; hostile detail escaped; no XSS execution)');
-  } finally {
-    await browser?.close(); server.closeAllConnections(); await new Promise(resolve => server.close(resolve));
-    offline.closeAllConnections(); await new Promise(resolve => offline.close(resolve)); await runtime.logger.close();
-    assert.equal(path.dirname(temp), path.resolve(os.tmpdir())); assert.ok(path.basename(temp).startsWith('kb-agent-mcp-ui-'));
-    fs.rmSync(temp, { recursive: true, force: true, maxRetries: 12, retryDelay: 200 });
-  }
-}
-main().catch(error => { console.error(error.stack); process.exitCode = 1; });
+'use strict';
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const http = require('node:http');
+const { createRequire } = require('node:module');
+const coreRoot = path.resolve(process.env.KB_CAPTURE_TEST_CORE_ROOT || path.join(__dirname, '../..'));
+const fromCore = createRequire(path.join(coreRoot, 'package.json'));
+const { createRuntime, initializeRuntime, createRequestHandler } = fromCore('./_site/lib/server-app');
+const { BridgeAdapter } = fromCore('./_site/lib/bridge-adapter');
+const { ModuleBridge } = fromCore('./_site/lib/module-bridge');
+const { findChrome } = require('./helpers/find-chrome');
+const { launchCdpBrowser, waitFor } = require('./helpers/cdp-browser');
+
+const HOSTILE_DETAIL = '<img src=x onerror="window.__kbXssProbe=1"> INJECT-STATUS-MARKER sk-abcdef123456';
+
+function clientFixture(client, label) {
+  const mcpCapable = client === 'claude' || client === 'codex';
+  return {
+    client, label, available: false, configFound: false,
+    knowledgeIntegration: { ok: true, state: 'installed' },
+    automaticContext: { supported: client !== 'opencode', configured: false, state: 'check-failed', detail: HOSTILE_DETAIL },
+    developmentCapture: { ok: true, state: 'installed', installed: true, detail: HOSTILE_DETAIL },
+    mcpStartup: mcpCapable ? { state: 'failed', checkedAt: new Date().toISOString(), scope: 'client:' + client, code: 'PROBE_TIMEOUT', expectedVersion: '9.9.9-test', detail: HOSTILE_DETAIL } : undefined,
+  };
+}
+
+async function main() {
+  const temp = fs.mkdtempSync(path.join(os.tmpdir(), 'kb-agent-mcp-ui-'));
+  const dataDir = path.join(temp, 'data');
+  const homeDir = path.join(temp, 'home');
+  const eventsHome = path.join(dataDir, 'events');
+  const offline = http.createServer((req, res) => { res.writeHead(503, { 'content-type': 'application/json' }); res.end(JSON.stringify({ ok: false, error: { message: 'offline stub' } })); });
+  await new Promise(resolve => offline.listen(0, '127.0.0.1', resolve));
+  const offlineUrl = 'http://127.0.0.1:' + offline.address().port;
+  const runtime = createRuntime({ dataDir, analysisOwner: 'engine', bridgeAdapter: new BridgeAdapter({ dataDir, bridgeHomeDir: eventsHome }), moduleBridge: new ModuleBridge({ terminalUrl: offlineUrl, engineUrl: offlineUrl, eventBridgeUrl: offlineUrl, vectorHubUrl: offlineUrl }) });
+  await initializeRuntime(runtime);
+  const server = http.createServer(createRequestHandler(runtime, { integrationOptions: { homeDir, env: {}, commandResolver: () => '' } }));
+  await new Promise(resolve => server.listen(0, '127.0.0.1', resolve));
+  const base = 'http://127.0.0.1:' + server.address().port;
+  const payload = JSON.stringify({ bridge: { ok: true }, scan: { state: 'ready' }, clients: [clientFixture('claude', 'Claude Code'), clientFixture('codex', 'Codex'), clientFixture('zcode', 'ZCode'), clientFixture('opencode', 'OpenCode')] });
+  let browser;
+  try {
+    browser = await launchCdpBrowser({ chrome: findChrome(), profileDir: path.join(temp, 'browser'), url: base, width: 1440, height: 900 });
+    const run = expression => browser.evaluate(expression);
+    const click = selector => run('document.querySelector(' + JSON.stringify(selector) + ').click()');
+    await run('(() => { const original = window.fetch; window.__originalFetch = original; window.fetch = (input, init) => { const url = String(input && input.url || input); if (url.includes(\'/api/integrations/status\')) { return Promise.resolve({ ok: true, json: async () => (' + payload + ') }); } return original(input, init); }; })()');
+    await click('#openSystem');
+    await waitFor(() => run("document.querySelectorAll('#agentCaptureList .agent-capture-row').length === 4"), 'capture rows render');
+    assert(await run("document.getElementById('agentCaptureList').textContent.includes('PROBE_TIMEOUT')"), 'the MCP startup failure code must be rendered for MCP-capable clients');
+    const claudeRowHtml = await run("document.querySelector('#agentCaptureList .agent-capture-row').innerHTML");
+    assert(claudeRowHtml.includes('&lt;img'), 'hostile mcpStartup detail must be HTML-escaped, got: ' + claudeRowHtml.slice(0, 300));
+    assert(!claudeRowHtml.includes('<img'), 'no raw hostile markup may reach the DOM');
+    assert.equal(await run('window.__kbXssProbe'), undefined, 'the hostile onerror must never execute');
+    const smalls = await run("[...document.querySelectorAll('#agentCaptureList small')].map(el => el.textContent).join('|')");
+    assert(smalls.split('|').some(text => text.startsWith('MCP')), 'the MCP diagnostic is its own line item, got: ' + smalls);
+    assert.equal(browser.exceptions.length, 0, JSON.stringify(browser.exceptions));
+    console.log('agent-capture-mcp-ui-test PASS (MCP line rendered separately; hostile detail escaped; no XSS execution)');
+  } finally {
+    await browser?.close(); server.closeAllConnections(); await new Promise(resolve => server.close(resolve));
+    offline.closeAllConnections(); await new Promise(resolve => offline.close(resolve)); await runtime.logger.close();
+    assert.equal(path.dirname(temp), path.resolve(os.tmpdir())); assert.ok(path.basename(temp).startsWith('kb-agent-mcp-ui-'));
+    fs.rmSync(temp, { recursive: true, force: true, maxRetries: 12, retryDelay: 200 });
+  }
+}
+main().catch(error => { console.error(error.stack); process.exitCode = 1; });