@sanqianx/project-knowledge 4.6.1

package/_site/lib/commit-conversation-binder.js

@@ -0,0 +1,246 @@
+const fs = require('fs');
+const { DomainError, validateProjectId } = require('./contracts');
+const { ConversationStore, sha256 } = require('./conversation-store');
+const { readDevelopmentEvents } = require('./conversation-exclusions');
+const { StorageLayout } = require('./storage-layout');
+
+function projectEvent(event) {
+  return {
+    eventId: event.eventId,
+    sequence: event.sequence,
+    content: event.content,
+    contentHash: event.contentHash,
+    capturedAt: event.capturedAt,
+  };
+}
+
+class CommitConversationBinder {
+  constructor(options = {}) {
+    this.layout = options.layout || new StorageLayout(options);
+    this.projectStore = options.projectStore;
+    this.conversationStore = options.conversationStore || new ConversationStore({
+      layout: this.layout,
+      projectStore: this.projectStore,
+      logger: options.logger,
+    });
+    this.logger = options.logger || null;
+  }
+
+  async log(level, event, message, context) {
+    if (this.logger && typeof this.logger[level] === 'function') await this.logger[level](event, message, context);
+  }
+
+  repoMatches(left, right) {
+    if (!left || !right) return false;
+    // workspaceId is the canonical primary key (I-06). commonDir/repoId are
+    // read-compat fallbacks for records stored before repo-identity/v1.
+    if (left.workspaceId && right.workspaceId) return String(left.workspaceId) === String(right.workspaceId);
+    if (left.commonDir && right.commonDir) return this.layout.pathsEqual(left.commonDir, right.commonDir);
+    if (left.repoId && right.repoId) return String(left.repoId) === String(right.repoId);
+    return false;
+  }
+
+  boundaryOrder(boundary) {
+    return Number.isInteger(boundary.journalSequence) ? boundary.journalSequence : boundary.bridgeCursorAtCommit;
+  }
+
+  previousBoundary(projectId, boundary) {
+    const order = this.boundaryOrder(boundary);
+    return this.conversationStore.listBoundaries(projectId)
+      .filter(candidate => candidate.commitSha !== boundary.commitSha
+        && this.repoMatches(candidate.repoIdentity, boundary.repoIdentity)
+        && this.boundaryOrder(candidate) < order)
+      .sort((left, right) => this.boundaryOrder(right) - this.boundaryOrder(left))[0] || null;
+  }
+
+  snapshotExists(projectId, commitSha) {
+    return fs.existsSync(this.layout.getProjectCommitConversationPath(projectId, commitSha));
+  }
+
+  async bind(input = {}) {
+    const projectId = validateProjectId(input.projectId);
+    const commitSha = this.layout.validateCommitSha(input.commitSha);
+    if (this.snapshotExists(projectId, commitSha)) return this.conversationStore.readSnapshot(projectId, commitSha);
+
+    if (this.projectStore) await this.conversationStore.importLegacyRequirements(projectId);
+    // Development Conversation reads are centralized: exclusions and Codex
+    // turn repair are identical here and in the query service.
+    const events = readDevelopmentEvents(this.conversationStore, projectId);
+    let boundary = null;
+    try { boundary = this.conversationStore.readBoundary(projectId, commitSha); }
+    catch (error) {
+      if (!error || error.code !== 'ENOENT') throw error;
+    }
+
+    const explicitEvents = events.filter(event => event.role === 'user' && event.explicitCommitSha === commitSha);
+    if (!boundary) {
+      const turns = this.buildExplicitTurns(explicitEvents);
+      return this.finalize(projectId, commitSha, {
+        repoIdentity: null,
+        parentSha: null,
+        boundaryStartCursor: null,
+        boundaryEndCursor: null,
+        status: turns.length ? 'available' : 'unavailable',
+        turns,
+        excludedFuturePromptCount: 0,
+      }, { reason: 'missing-commit-boundary' });
+    }
+
+    const previous = this.previousBoundary(projectId, boundary);
+    const state = this.projectStore ? this.projectStore.readState(projectId) : { conversationBaselineCursor: null };
+    const startCursor = previous ? previous.bridgeCursorAtCommit : state.conversationBaselineCursor;
+    const endCursor = boundary.bridgeCursorAtCommit;
+    const selected = new Map();
+    let ambiguousCount = 0;
+    let excludedFuturePromptCount = 0;
+
+    for (const event of explicitEvents) {
+      if (event.repoIdentity && boundary.repoIdentity && !this.repoMatches(event.repoIdentity, boundary.repoIdentity)) {
+        ambiguousCount += 1;
+        continue;
+      }
+      if (!event.turnId) { ambiguousCount += 1; continue; }
+      selected.set(event.turnId, 'explicit');
+    }
+
+    if (Number.isInteger(startCursor)) {
+      for (const event of events) {
+        if (event.role !== 'user' || event.sequence == null || event.explicitCommitSha) continue;
+        if (!this.repoMatches(event.repoIdentity, boundary.repoIdentity)) {
+          if (event.sequence > startCursor && event.sequence <= endCursor && !event.repoIdentity) ambiguousCount += 1;
+          continue;
+        }
+        if (event.sequence > endCursor) {
+          excludedFuturePromptCount += 1;
+          continue;
+        }
+        if (event.sequence <= startCursor) continue;
+        // Automatic direct evidence requires exact identity. Legacy stored
+        // 'high'/'trusted' translate to exact for old known data only;
+        // 'explicit' is the explicit-fallback tier (I-18: no synthetic).
+        const rawConfidence = String(event.identityConfidence || '');
+        const effectiveConfidence = rawConfidence === 'high' || rawConfidence === 'trusted' ? 'exact' : rawConfidence;
+        if (!event.turnId || !['exact', 'explicit'].includes(effectiveConfidence)) {
+          ambiguousCount += 1;
+          continue;
+        }
+        selected.set(event.turnId, 'direct');
+      }
+
+      for (const turnId of boundary.openTurnIdsAtCommit) {
+        if (selected.has(turnId)) continue;
+        const user = events.find(event => event.role === 'user'
+          && event.turnId === turnId
+          && event.sequence != null
+          && event.sequence <= startCursor
+          && this.repoMatches(event.repoIdentity, boundary.repoIdentity));
+        const closedAt = user && user.developmentTurnClosedAtSequence;
+        if (user && !(Number.isInteger(closedAt) && closedAt <= startCursor)) {
+          selected.set(turnId, 'shared-spanning');
+        }
+      }
+    }
+
+    const turns = [];
+    for (const [turnId, bindingKind] of selected) {
+      const turnEvents = events.filter(event => event.turnId === turnId).sort((left, right) => {
+        if (left.sequence == null) return 1;
+        if (right.sequence == null) return -1;
+        return left.sequence - right.sequence;
+      });
+      const userEvents = turnEvents.filter(event => event.role === 'user'
+        && (bindingKind === 'explicit' || (event.sequence != null && event.sequence <= endCursor)));
+      if (!userEvents.length) continue;
+      const first = userEvents[0];
+      // I-13: no event beyond the commit boundary may enter a frozen
+      // snapshot — including assistant replies that arrived after the
+      // boundary but before a delayed binder run.
+      const assistantEvents = turnEvents.filter(event => event.role === 'assistant'
+        && (bindingKind === 'explicit' || (event.sequence != null && event.sequence <= endCursor)));
+      turns.push({
+        turnId,
+        source: first.source,
+        sessionId: first.sessionId,
+        bindingKind,
+        userEvents: userEvents.map(projectEvent),
+        assistantEvents: assistantEvents.map(projectEvent),
+      });
+    }
+    turns.sort((left, right) => {
+      const a = left.userEvents[0].sequence;
+      const b = right.userEvents[0].sequence;
+      if (a == null) return 1;
+      if (b == null) return -1;
+      return a - b;
+    });
+
+    let status = turns.length ? 'available' : 'no-new-user-prompt';
+    let reason = turns.length ? 'sequence-window' : 'no-new-user-prompt';
+    if (!Number.isInteger(startCursor)) {
+      status = explicitEvents.length && turns.length ? 'available' : 'unavailable';
+      reason = 'conversation-baseline-unavailable';
+    } else if (ambiguousCount > 0 && !turns.length) {
+      status = 'ambiguous';
+      reason = 'turn-or-repo-identity-ambiguous';
+    }
+
+    return this.finalize(projectId, commitSha, {
+      repoIdentity: boundary.repoIdentity,
+      parentSha: boundary.parentShas[0] || null,
+      boundaryStartCursor: startCursor,
+      boundaryEndCursor: endCursor,
+      status,
+      turns,
+      excludedFuturePromptCount,
+    }, { reason, ambiguousCount, previousBoundaryCommit: previous && previous.commitSha || null });
+  }
+
+  buildExplicitTurns(events) {
+    return events.filter(event => event.turnId).map(event => ({
+      turnId: event.turnId,
+      source: event.source,
+      sessionId: event.sessionId,
+      bindingKind: 'explicit',
+      userEvents: [projectEvent(event)],
+      assistantEvents: [],
+    }));
+  }
+
+  async finalize(projectId, commitSha, snapshotInput, decision) {
+    const snapshot = this.conversationStore.writeSnapshot(projectId, {
+      commitSha,
+      ...snapshotInput,
+      finalizedAt: new Date().toISOString(),
+    });
+    await this.log(snapshot.status === 'ambiguous' || snapshot.status === 'unavailable' ? 'warn' : 'info', 'conversation.commit_snapshot_frozen', 'Commit conversation snapshot was frozen.', {
+      projectId,
+      commitSha,
+      component: 'commit-conversation-binder',
+      phase: 'snapshot-frozen',
+      context: {
+        snapshotHash: snapshot.snapshotHash,
+        status: snapshot.status,
+        turnCount: snapshot.turns.length,
+        userEventCount: snapshot.turns.reduce((total, turn) => total + turn.userEvents.length, 0),
+        assistantEventCount: snapshot.turns.reduce((total, turn) => total + turn.assistantEvents.length, 0),
+        decision,
+      },
+    });
+    return snapshot;
+  }
+}
+
+function snapshotRequirementRecords(snapshot) {
+  return snapshot.turns.flatMap(turn => turn.userEvents.map(event => ({
+    id: event.eventId,
+    client: turn.source,
+    sessionId: turn.sessionId,
+    ts: event.capturedAt,
+    requirement: event.content,
+    requirementHash: event.contentHash,
+    turnId: turn.turnId,
+    bindingKind: turn.bindingKind,
+  })));
+}
+
+module.exports = { CommitConversationBinder, snapshotRequirementRecords, projectEvent, sha256 };

package/_site/lib/commit-processing-ledger.js

@@ -0,0 +1,27 @@
+const fs = require('fs');
+const { DomainError, validateProjectId } = require('./contracts');
+const { validateSha } = require('./scanner');
+const { StorageLayout } = require('./storage-layout');
+const AtomicFile = require('./atomic-file');
+
+class CommitProcessingLedger {
+  constructor(options = {}) { this.layout = options.layout || new StorageLayout(options); this.atomic = options.atomic || AtomicFile; }
+  filePath(projectId, commitSha) { return this.layout.getRuntimePath('processed-commits', validateProjectId(projectId), `${validateSha(commitSha)}.json`); }
+  read(projectId, commitSha) {
+    const file = this.filePath(projectId, commitSha);
+    if (!fs.existsSync(file)) return null;
+    return this.atomic.readJsonStrict(file, { category: 'commit-processing-record', validate: value => {
+      if (!value || value.schema !== 'commit-processing-record/v1' || value.projectId !== projectId || value.commitSha !== commitSha || value.status !== 'completed') {
+        throw new DomainError('DATA_CORRUPT', 'Commit processing ledger record is corrupt.', { status: 500 });
+      }
+      return value;
+    } });
+  }
+  complete(projectId, commitSha, fields = {}) {
+    const record = { schema: 'commit-processing-record/v1', projectId: validateProjectId(projectId), commitSha: validateSha(commitSha), status: 'completed', ...fields, completedAt: new Date().toISOString() };
+    this.atomic.writeJsonAtomic(this.filePath(projectId, commitSha), record);
+    return record;
+  }
+}
+
+module.exports = { CommitProcessingLedger };

package/_site/lib/commit-prompt.js

@@ -0,0 +1,202 @@
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const {
+  DEFAULT_COMMIT_PROMPT_TEMPLATE,
+  PROMPT_TEMPLATE_VERSION,
+  normalizeAutomationConfig,
+  renderTemplate,
+} = require('./automation-config');
+
+const REQUIREMENT_UNAVAILABLE = '需求上下文未记录。只能记录代码可以证明的变化，不得猜测业务目的。';
+const REQUIRED_SECTIONS = Object.freeze([
+  ['userRequirement', '用户需求'],
+  ['aiConversationEvidence', 'AI 对话证据'],
+  ['commitMetadata', 'Commit 信息'],
+  ['actualChanges', 'Commit 实际变更文件'],
+  ['actualPatch', 'Commit 实际 Patch'],
+  ['existingKnowledge', '现有相关知识'],
+]);
+
+function sha256(value) {
+  return `sha256:${crypto.createHash('sha256').update(value, 'utf8').digest('hex')}`;
+}
+
+function formatRequirements(records) {
+  if (!Array.isArray(records) || records.length === 0) return REQUIREMENT_UNAVAILABLE;
+  return records.map(record => [
+    `- requirementId: ${record.id}`,
+    `  client/session: ${record.client}/${record.sessionId}`,
+    `  recordedAt: ${record.ts}`,
+    '  requirement: |',
+    ...String(record.requirement || '').split(/\r?\n/).map(line => `    ${line}`),
+  ].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)'}`,
+    `  binding: ${turn.bindingKind}`,
+    `  capturedAt: ${event.capturedAt}`,
+    '  userPrompt: |',
+    ...String(event.content || '').split(/\r?\n/).map(line => `    ${line}`),
+  ].join('\n'))).join('\n');
+}
+
+function formatAssistantEvidence(snapshot) {
+  if (!snapshot || !Array.isArray(snapshot.turns)) return '(no assistant conversation evidence was frozen)';
+  const entries = snapshot.turns.flatMap(turn => turn.assistantEvents.map(event => [
+    `- turnId: ${turn.turnId}`,
+    `  eventId: ${event.eventId}`,
+    `  capturedAt: ${event.capturedAt}`,
+    '  assistantResponse: |',
+    ...String(event.content || '').split(/\r?\n/).map(line => `    ${line}`),
+  ].join('\n')));
+  return entries.length ? entries.join('\n') : '(no assistant conversation evidence was frozen)';
+}
+
+function formatCommitMetadata(evidence) {
+  return [
+    `fullSha: ${evidence.commitSha}`,
+    `parents: ${(evidence.parents || []).join(', ') || '(root commit)'}`,
+    `author: ${evidence.author || ''}`,
+    `date: ${evidence.date || ''}`,
+    `subject: ${evidence.subject || ''}`,
+    `branchAtScan: ${evidence.branch || '(detached/unavailable)'}`,
+    `patchMode: ${evidence.patchMode}`,
+    `patchHash: ${evidence.patchHash}`,
+    `patchBytes: ${evidence.patchBytes}`,
+  ].join('\n');
+}
+
+function formatChanges(evidence) {
+  if (!evidence.files || evidence.files.length === 0) return '(no changed paths reported by Git)';
+  return evidence.files.map(file => {
+    const rename = file.oldPath ? ` ${file.oldPath} -> ${file.path}` : ` ${file.path}`;
+    const stats = file.binary ? ' binary' : ` +${file.added == null ? '?' : file.added}/-${file.deleted == null ? '?' : file.deleted}`;
+    return `- ${file.status}${rename}${stats}`;
+  }).join('\n');
+}
+
+function formatPatch(evidence) {
+  if (!evidence.patchChunked) return evidence.patch || '(empty patch)';
+  const bundle = evidence.evidenceBundle || {};
+  return [
+    '[EXACT PATCH AVAILABLE AS READ-ONLY CHUNKS]',
+    `fullPatchHash: ${evidence.patchHash}`,
+    `fullPatchBytes: ${evidence.patchBytes}`,
+    `patchManifestHash: ${bundle.manifestHash || '(unavailable)'}`,
+    `patchManifestPath: ${bundle.manifestPath || '(unavailable)'}`,
+    `chunkCount: ${bundle.chunkCount == null ? '(unavailable)' : bundle.chunkCount}`,
+    'Read patch-manifest.json, then Read exact patch chunks in manifest sequence. The chunks cover the full Git diff.',
+    'Do not read the source worktree and do not infer unread evidence.',
+  ].join('\n');
+}
+
+function formatExistingKnowledge(existing) {
+  if (!existing || !Array.isArray(existing.entries) || existing.entries.length === 0) {
+    return '(no existing project knowledge was available)';
+  }
+  const sections = existing.entries.map(entry => `--- ${entry.path} (${entry.hash}) ---\n${entry.content}`);
+  if (existing.omitted && existing.omitted.length) {
+    sections.push(`[EXISTING KNOWLEDGE OMITTED: ${existing.omitted.join(', ')}]`);
+  }
+  return sections.join('\n\n');
+}
+
+function ensureRequiredSections(template, rendered, vars) {
+  const missing = REQUIRED_SECTIONS.filter(([name]) => !new RegExp(`\\{\\{\\s*${name}\\s*\\}\\}`, 'i').test(template));
+  if (!missing.length) return rendered;
+  const footer = missing.map(([name, label]) => `${label}：\n${vars[name]}`).join('\n\n');
+  return `${rendered.trimEnd()}\n\n${footer}`;
+}
+
+function renderCommitPrompt(input = {}) {
+  const config = input.config || {};
+  const evidence = input.evidence || {};
+  const automation = normalizeAutomationConfig(config.automation);
+  const template = automation.commitPromptTemplate || DEFAULT_COMMIT_PROMPT_TEMPLATE;
+  const vars = {
+    userRequirement: input.conversationSnapshot
+      ? formatConversationUserTruth(input.conversationSnapshot)
+      : formatRequirements(input.requirements),
+    aiConversationEvidence: formatAssistantEvidence(input.conversationSnapshot),
+    commitMetadata: formatCommitMetadata(evidence),
+    actualChanges: formatChanges(evidence),
+    actualPatch: formatPatch(evidence),
+    existingKnowledge: formatExistingKnowledge(input.existingKnowledge),
+    projectId: config.projectId || input.projectId || '',
+    displayName: config.displayName || config.projectId || '',
+    knowledgePath: config.knowledgePath || '',
+    repoPath: config.repoPath || '',
+    commitHash: evidence.commitSha || '',
+    commitSubject: evidence.subject || '',
+    commitAuthor: evidence.author || '',
+    commitDate: evidence.date || '',
+    branch: evidence.branch || '',
+    changedFiles: formatChanges(evidence),
+    diffSummary: formatPatch(evidence),
+  };
+  const rendered = ensureRequiredSections(template, renderTemplate(template, vars), vars).trimEnd() + '\n';
+  return {
+    prompt: rendered,
+    promptHash: sha256(rendered),
+    promptTemplateVersion: PROMPT_TEMPLATE_VERSION,
+    promptLength: rendered.length,
+    vars,
+  };
+}
+
+class KnowledgeEvidenceReader {
+  constructor(options = {}) {
+    this.maxBytes = Number(options.maxBytes || 256 * 1024);
+    this.maxFiles = Number(options.maxFiles || 24);
+  }
+
+  read(config) {
+    const root = config && config.knowledgePath ? path.resolve(config.knowledgePath) : '';
+    if (!root || !fs.existsSync(root) || !fs.statSync(root).isDirectory()) return { entries: [], omitted: [] };
+    const realRoot = fs.realpathSync(root);
+    const files = [];
+    const walk = current => {
+      for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (entry.isSymbolicLink()) continue;
+        const absolute = path.join(current, entry.name);
+        if (entry.isDirectory()) walk(absolute);
+        else if (entry.isFile() && entry.name.toLowerCase().endsWith('.md')) files.push(absolute);
+      }
+    };
+    walk(root);
+    let used = 0;
+    const entries = [];
+    const omitted = [];
+    for (const file of files) {
+      const realFile = fs.realpathSync(file);
+      const relativeBoundary = path.relative(realRoot, realFile);
+      if (relativeBoundary.startsWith('..') || path.isAbsolute(relativeBoundary)) continue;
+      const relativePath = path.relative(root, file).replace(/\\/g, '/');
+      const content = fs.readFileSync(file, 'utf8');
+      const bytes = Buffer.byteLength(content, 'utf8');
+      if (entries.length >= this.maxFiles || used + bytes > this.maxBytes) {
+        omitted.push(relativePath);
+        continue;
+      }
+      used += bytes;
+      entries.push({ path: relativePath, hash: sha256(content), content });
+    }
+    return { entries, omitted, totalBytes: used, limitBytes: this.maxBytes, limitFiles: this.maxFiles };
+  }
+}
+
+module.exports = {
+  REQUIREMENT_UNAVAILABLE,
+  KnowledgeEvidenceReader,
+  formatRequirements,
+  formatConversationUserTruth,
+  formatAssistantEvidence,
+  renderCommitPrompt,
+  sha256,
+};