@sanqianx/project-knowledge 5.0.24 → 5.0.26

package/_modules/knowledge-engine/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanqianx/ai-coding-knowledge-engine",
-  "version": "0.2.7-rc.10",
+  "version": "0.2.7-rc.11",
   "description": "Knowledge engine module for project-knowledge: commit-boundary triggered knowledge analysis/generation (trigger plane) and retrieval for development assistants (retrieval plane).",
   "license": "Apache-2.0",
   "main": "src/server.js",

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

@@ -187,10 +187,34 @@ class EngineCoordinator extends EventEmitter {
           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;
+            // The history floor is the tracking baseline: commits at or before it
+            // are pre-existing history and are never analysed. The analysed head
+            // is not the floor - a captured commit behind the head that was never
+            // completed and never attempted was MISSED (its boundary event
+            // arrived after the head moved past it), and dropping it would
+            // discard durable evidence for good. But auto-analysing it is worse:
+            // promotion would advance the head BACKWARDS to the old commit and
+            // its replace/delete operations could overwrite the newer knowledge
+            // the head already promoted at the same paths. Safety and existing
+            // commit order win: the late commit is flagged into a durable
+            // registry awaiting CONTROLLED handling - no run, no pointer
+            // movement, no fake success, no silent drop. A completed commit is
+            // held by the processing ledger; a previously failed or interrupted
+            // commit keeps its claim snapshot and is only re-run on an explicit
+            // user retry.
+            const floor = p.trackingStartCommit || null;
+            const head = p.runtime.lastAnalyzedCommit || null;
+            const isAncestorOf = async ancestor => (await execGit(p.repoPath, ['merge-base', '--is-ancestor', event.commitSha, ancestor])).ok;
+            const preBaseline = Boolean(floor) && (floor === event.commitSha || await isAncestorOf(floor));
+            const atHead = Boolean(head) && head === event.commitSha;
+            const behindHead = Boolean(head) && !atHead && await isAncestorOf(head);
             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 });
+            const attempted = fs.existsSync(this.reconciler.claimStore.filePath(p.projectId, event.commitSha));
+            const skip = Boolean(completed) || preBaseline || atHead || (behindHead && attempted);
+            if (!skip && this.store.getProject(p.projectId)?.enabled) {
+              if (behindHead) await this.flagLateCommit(p, { commitSha: event.commitSha, journalId: journal.journalId, journalSequence: event.sequence, analysedHead: head });
+              else this.enqueue({ projectId: p.projectId, commitSha: event.commitSha, trigger: 'git-hook', journalId: journal.journalId, journalSequence: event.sequence });
+            }
           }
         }
       } catch (error) { error.journalContext = { projectId: p?.projectId, sequence: event.sequence, source: event.source }; throw error; }
@@ -200,6 +224,27 @@ class EngineCoordinator extends EventEmitter {
     if (through > cursor) this.store.setJournalCursor(journal.journalId, through);
     await this.bridge.ackConsumerCursor('knowledge-engine', through, { journalId: journal.journalId });
   }
+  // A late captured commit is durable evidence, but it can never be auto-healed
+  // here: promoting it would regress lastAnalyzedCommit and could overwrite
+  // newer knowledge at the same paths. It is registered (idempotently) for
+  // CONTROLLED handling instead - the registry is part of the project runtime,
+  // so it survives restarts and surfaces via /api/snapshot; the event log and
+  // the warn diagnostic make the out-of-order state visible without any fake
+  // success. Discharging a late commit is an explicit operator decision.
+  async flagLateCommit(project, { commitSha, journalId, journalSequence, analysedHead }) {
+    const runtime = this.store.readRuntime(project.projectId);
+    const known = (runtime.lateCommits || []).some(entry => entry.commitSha === commitSha)
+      || this.store.listRuns(project.projectId).some(run => run.commitSha === commitSha);
+    if (known) return;
+    await this.store.updateRuntime(project.projectId, draft => {
+      draft.lateCommits = draft.lateCommits || [];
+      if (!draft.lateCommits.some(entry => entry.commitSha === commitSha)) {
+        draft.lateCommits.push({ commitSha, firstSeenAt: new Date().toISOString(), journalId, journalSequence, analysedHeadAtCapture: analysedHead });
+      }
+    });
+    this.store.addEvent({ type: 'knowledge.journal', projectId: project.projectId, commitSha, summary: `捕获到晚到的旧提交 ${commitSha.slice(0, 12)}，已登记为需受控处理，未自动分析` });
+    await this.diagnostics.warn('reconcile.late_commit_flagged', '晚到的旧提交已登记为待受控处理：不自动分析、不推进分析头、不修改知识树。', { projectId: project.projectId, commitSha, phase: 'consuming', context: { journalId, journalSequence, analysedHead } });
+  }
   pump() {
     if (this.closed || !this.executionEnabled) return;
     const queued = this.store.state.runs.filter(r => r.state === 'queued' && (!this.allowedProjects || this.allowedProjects.has(r.projectId))).sort((a, b) => a.sequence - b.sequence);

package/_modules/knowledge-engine/src/runtime/automation-config.js

@@ -1,140 +1,140 @@
-const path = require('path');
-
-const PERMISSION_MODES = new Set(['plan', 'default', 'acceptEdits', 'auto', 'bypassPermissions']);
-const PROMPT_TEMPLATE_VERSION = 2;
-
-const DEFAULT_COMMIT_PROMPT_TEMPLATE = `你正在根据一个 Git Commit 的冻结证据维护项目知识库。
-
-用户需求：
-{{userRequirement}}
-
-Commit 信息：
-{{commitMetadata}}
-
-Commit 实际变更文件：
-{{actualChanges}}
-
-Commit 实际 Patch：
-{{actualPatch}}
-
-现有相关知识：
-{{existingKnowledge}}
-
-请完成以下判断，并只输出符合 staging manifest 合同的知识变更：
-1. 比较用户需求与实际实现是否一致；没有可靠需求时不得猜测业务目的。
-2. 只记录 Commit、Patch 和现有知识能够证明的事实。
-3. 明确需要新增、更新或删除哪些知识；删除必须有实际变更证据。
-4. 不得修改源码、最终知识目录、其他项目或派生索引。
-5. Patch 使用 chunk evidence 时，必须从只读 manifest 按序读取所需 chunk；不得从源码工作树补读或猜测。`;
-
-const READ_TOOLS = ['Read'];
-const WRITE_TOOLS = ['Edit', 'Write', 'MultiEdit'];
-
-function normalizePermissionMode(value) {
-  return PERMISSION_MODES.has(value) ? value : 'default';
-}
-
-function normalizeAutomationConfig(input) {
-  const source = input && typeof input === 'object' ? input : {};
-  const explicit = typeof source.commitPromptTemplate === 'string' && source.commitPromptTemplate.trim();
-  const legacy = typeof source.hookPromptTemplate === 'string' && source.hookPromptTemplate.trim();
-  return {
-    enabled: source.enabled !== false,
-    commitPromptTemplate: explicit || legacy || DEFAULT_COMMIT_PROMPT_TEMPLATE,
-    promptTemplateVersion: PROMPT_TEMPLATE_VERSION,
-    legacyPromptOverride: !explicit && Boolean(legacy),
-  };
-}
-
-function normalizeClaudeWorkbenchConfig(input) {
-  const source = input && typeof input === 'object' ? input : {};
-  return { permissionMode: normalizePermissionMode(source.permissionMode) };
-}
-
-function renderTemplate(template, vars) {
-  const source = typeof template === 'string' && template.trim() ? template : DEFAULT_COMMIT_PROMPT_TEMPLATE;
-  const safeVars = vars && typeof vars === 'object' ? vars : {};
-  return source.replace(/\{\{\s*([A-Za-z][A-Za-z0-9_]*)\s*\}\}/g, (match, name) => {
-    if (!Object.prototype.hasOwnProperty.call(safeVars, name)) return match;
-    const value = safeVars[name];
-    return value == null ? '' : String(value);
-  });
-}
-
-function normalizePathForCompare(value) {
-  if (!value || typeof value !== 'string') return '';
-  const normalized = path.resolve(value).replace(/[\\/]+$/, '');
-  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
-}
-
-function pathsReferToSameLocation(leftValue, rightValue) {
-  const left = normalizePathForCompare(leftValue);
-  const right = normalizePathForCompare(rightValue);
-  return Boolean(left && right && left === right);
-}
-
-function isInsidePath(root, target) {
-  if (!root || !target) return false;
-  const rootAbs = path.resolve(root);
-  const targetAbs = path.resolve(rootAbs, target);
-  const relative = path.relative(rootAbs, targetAbs);
-  return relative === '' || Boolean(relative && !relative.startsWith('..') && !path.isAbsolute(relative));
-}
-
-function extractToolPaths(toolName, input) {
-  if (!input || typeof input !== 'object') return [];
-  const candidates = [];
-  for (const key of ['file_path', 'path', 'notebook_path']) {
-    if (typeof input[key] === 'string') candidates.push(input[key]);
-  }
-  if (toolName === 'MultiEdit' && typeof input.file_path === 'string') candidates.push(input.file_path);
-  return [...new Set(candidates)];
-}
-
-function buildAutomationToolPolicy(options = {}) {
-  const stagingPath = options.stagingPath || options.kbPath || '';
-  const evidenceRoot = options.evidenceRoot || '';
-  return {
-    kind: 'knowledge-staging',
-    stagingPath,
-    evidenceRoot,
-    readRoots: [evidenceRoot, stagingPath].filter(Boolean),
-    writeRoot: stagingPath,
-    allowedTools: [...READ_TOOLS, ...WRITE_TOOLS],
-    canWriteKb: false,
-    canWriteStaging: true,
-    allowReadOnlyBash: false,
-  };
-}
-
-function evaluateAutomationToolUse(policy, toolName, input) {
-  if (!policy || policy.kind !== 'knowledge-staging') return { behavior: 'ask', reason: 'no staging policy' };
-  if (!policy.allowedTools.includes(toolName)) return { behavior: 'deny', reason: `tool is not allowed: ${toolName}` };
-  const paths = extractToolPaths(toolName, input);
-  if (!paths.length) return { behavior: 'deny', reason: `${toolName} has no explicit file path` };
-  for (const filePath of paths) {
-    if (toolName === 'Read') {
-      if (!(policy.readRoots || []).some(root => isInsidePath(root, filePath))) {
-        return { behavior: 'deny', reason: `path outside read-only evidence/output roots: ${filePath}` };
-      }
-    } else if (!isInsidePath(policy.writeRoot || policy.stagingPath, filePath)) {
-      return { behavior: 'deny', reason: `path outside writable run output: ${filePath}` };
-    }
-  }
-  return { behavior: 'allow', reason: toolName === 'Read' ? 'path is inside an isolated read root' : 'path is inside the isolated writable output root' };
-}
-
-module.exports = {
-  PERMISSION_MODES,
-  PROMPT_TEMPLATE_VERSION,
-  DEFAULT_COMMIT_PROMPT_TEMPLATE,
-  normalizePermissionMode,
-  normalizeAutomationConfig,
-  normalizeClaudeWorkbenchConfig,
-  renderTemplate,
-  normalizePathForCompare,
-  pathsReferToSameLocation,
-  isInsidePath,
-  buildAutomationToolPolicy,
-  evaluateAutomationToolUse,
-};
+const path = require('path');
+
+const PERMISSION_MODES = new Set(['plan', 'default', 'acceptEdits', 'auto', 'bypassPermissions']);
+const PROMPT_TEMPLATE_VERSION = 2;
+
+const DEFAULT_COMMIT_PROMPT_TEMPLATE = `你正在根据一个 Git Commit 的冻结证据维护项目知识库。
+
+用户需求：
+{{userRequirement}}
+
+Commit 信息：
+{{commitMetadata}}
+
+Commit 实际变更文件：
+{{actualChanges}}
+
+Commit 实际 Patch：
+{{actualPatch}}
+
+现有相关知识：
+{{existingKnowledge}}
+
+请完成以下判断，并只输出符合 staging manifest 合同的知识变更：
+1. 比较用户需求与实际实现是否一致；没有可靠需求时不得猜测业务目的。
+2. 只记录 Commit、Patch 和现有知识能够证明的事实。
+3. 明确需要新增、更新或删除哪些知识；删除必须有实际变更证据。
+4. 不得修改源码、最终知识目录、其他项目或派生索引。
+5. Patch 使用 chunk evidence 时，必须从只读 manifest 按序读取所需 chunk；不得从源码工作树补读或猜测。`;
+
+const READ_TOOLS = ['Read'];
+const WRITE_TOOLS = ['Edit', 'Write', 'MultiEdit'];
+
+function normalizePermissionMode(value) {
+  return PERMISSION_MODES.has(value) ? value : 'default';
+}
+
+function normalizeAutomationConfig(input) {
+  const source = input && typeof input === 'object' ? input : {};
+  const explicit = typeof source.commitPromptTemplate === 'string' && source.commitPromptTemplate.trim();
+  const legacy = typeof source.hookPromptTemplate === 'string' && source.hookPromptTemplate.trim();
+  return {
+    enabled: source.enabled !== false,
+    commitPromptTemplate: explicit || legacy || DEFAULT_COMMIT_PROMPT_TEMPLATE,
+    promptTemplateVersion: PROMPT_TEMPLATE_VERSION,
+    legacyPromptOverride: !explicit && Boolean(legacy),
+  };
+}
+
+function normalizeClaudeWorkbenchConfig(input) {
+  const source = input && typeof input === 'object' ? input : {};
+  return { permissionMode: normalizePermissionMode(source.permissionMode) };
+}
+
+function renderTemplate(template, vars) {
+  const source = typeof template === 'string' && template.trim() ? template : DEFAULT_COMMIT_PROMPT_TEMPLATE;
+  const safeVars = vars && typeof vars === 'object' ? vars : {};
+  return source.replace(/\{\{\s*([A-Za-z][A-Za-z0-9_]*)\s*\}\}/g, (match, name) => {
+    if (!Object.prototype.hasOwnProperty.call(safeVars, name)) return match;
+    const value = safeVars[name];
+    return value == null ? '' : String(value);
+  });
+}
+
+function normalizePathForCompare(value) {
+  if (!value || typeof value !== 'string') return '';
+  const normalized = path.resolve(value).replace(/[\\/]+$/, '');
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+function pathsReferToSameLocation(leftValue, rightValue) {
+  const left = normalizePathForCompare(leftValue);
+  const right = normalizePathForCompare(rightValue);
+  return Boolean(left && right && left === right);
+}
+
+function isInsidePath(root, target) {
+  if (!root || !target) return false;
+  const rootAbs = path.resolve(root);
+  const targetAbs = path.resolve(rootAbs, target);
+  const relative = path.relative(rootAbs, targetAbs);
+  return relative === '' || Boolean(relative && !relative.startsWith('..') && !path.isAbsolute(relative));
+}
+
+function extractToolPaths(toolName, input) {
+  if (!input || typeof input !== 'object') return [];
+  const candidates = [];
+  for (const key of ['file_path', 'path', 'notebook_path']) {
+    if (typeof input[key] === 'string') candidates.push(input[key]);
+  }
+  if (toolName === 'MultiEdit' && typeof input.file_path === 'string') candidates.push(input.file_path);
+  return [...new Set(candidates)];
+}
+
+function buildAutomationToolPolicy(options = {}) {
+  const stagingPath = options.stagingPath || options.kbPath || '';
+  const evidenceRoot = options.evidenceRoot || '';
+  return {
+    kind: 'knowledge-staging',
+    stagingPath,
+    evidenceRoot,
+    readRoots: [evidenceRoot, stagingPath].filter(Boolean),
+    writeRoot: stagingPath,
+    allowedTools: [...READ_TOOLS, ...WRITE_TOOLS],
+    canWriteKb: false,
+    canWriteStaging: true,
+    allowReadOnlyBash: false,
+  };
+}
+
+function evaluateAutomationToolUse(policy, toolName, input) {
+  if (!policy || policy.kind !== 'knowledge-staging') return { behavior: 'ask', reason: 'no staging policy' };
+  if (!policy.allowedTools.includes(toolName)) return { behavior: 'deny', reason: `tool is not allowed: ${toolName}` };
+  const paths = extractToolPaths(toolName, input);
+  if (!paths.length) return { behavior: 'deny', reason: `${toolName} has no explicit file path` };
+  for (const filePath of paths) {
+    if (toolName === 'Read') {
+      if (!(policy.readRoots || []).some(root => isInsidePath(root, filePath))) {
+        return { behavior: 'deny', reason: `path outside read-only evidence/output roots: ${filePath}` };
+      }
+    } else if (!isInsidePath(policy.writeRoot || policy.stagingPath, filePath)) {
+      return { behavior: 'deny', reason: `path outside writable run output: ${filePath}` };
+    }
+  }
+  return { behavior: 'allow', reason: toolName === 'Read' ? 'path is inside an isolated read root' : 'path is inside the isolated writable output root' };
+}
+
+module.exports = {
+  PERMISSION_MODES,
+  PROMPT_TEMPLATE_VERSION,
+  DEFAULT_COMMIT_PROMPT_TEMPLATE,
+  normalizePermissionMode,
+  normalizeAutomationConfig,
+  normalizeClaudeWorkbenchConfig,
+  renderTemplate,
+  normalizePathForCompare,
+  pathsReferToSameLocation,
+  isInsidePath,
+  buildAutomationToolPolicy,
+  evaluateAutomationToolUse,
+};